Poor buffer handling is implicated in many security issues that involve buffer overruns. The functions defined in Strsafe.h provide additional processing for proper buffer handling in your code. For this reason, they are intended to replace their built-in C/C++ counterparts as well as specific Microsoft Windows implementations. Strsafe.h may be obtained by downloading the Windows Core software development kit (SDK) from the SDK Update Site.
The advantages of the Strsafe functions include:
- The size of the destination buffer is always provided to the function to ensure that the function does not write past the end of the buffer.
- Buffers are guaranteed to be null-terminated, even if the operation truncates the intended result.
- All functions return an HRESULT, with only one possible success code (S_OK).
- Each function is available in a corresponding character count (cch) or byte count (cb) version.
- Most functions have an extended ("Ex") version available for advanced functionality.
See the following sections for details.
Strsafe.h character count functions
The following functions use a character count rather than a byte count.
| Strsafe.h function | Replaces |
|---|
| StringCchCat StringCchCatEx | strcat, wcscat, lstrcat, strcat, StrCatBuff, _tcscat, _ftcscat |
| StringCchCatN StringCchCatNEx | strncat, StrNCat |
| StringCchCopy StringCchCopyEx | strcpy, wcscpy, lstrcpy, strcpy, _tcscpy, _ftcscpy |
| StringCchCopyN StringCchCopyNEx | strncpy |
| StringCchGets StringCchGetsEx | gets, _getws, _getts |
| StringCchPrintf StringCchPrintfEx | sprintf, swprintf, wsprintf, wnsprintf, _stprintf, _snprintf, _snwprintf, _sntprintf |
| StringCchVPrintf StringCchVPrintfEx | vsprintf, vswprintf, wvsprintf, wvnsprintf, _vstprintf, _vsnprintf, _vsnwprintf, _vsntprintf |
| StringCchLength | strlen |
Strsafe.h byte count functions
The following functions use a byte count rather than a character count.
| Strsafe.h function | Replaces |
|---|
| StringCbCat StringCbCatEx | strcat, wcscat, lstrcat, strcat, StrCatBuff, _tcscat, _ftcscat |
| StringCbCatN StringCbCatNEx | strncat, StrNCat |
| StringCbCopy StringCbCopyEx | strcpy, wcscpy, lstrcpy, strcpy, _tcscpy, _ftcscpy |
| StringCbCopyN StringCbCopyNEx | strncpy |
| StringCbGets StringCbGetsEx | gets, _getws, _getts |
| StringCbPrintf StringCbPrintfEx | sprintf, swprintf, wsprintf, wnsprintf, _stprintf, _snprintf, _snwprintf, _sntprintf |
| StringCbVPrintf StringCbVPrintfEx | vsprintf, vswprintf, wvsprintf, wvnsprintf, _vstprintf, _vsnprintf, _vsnwprintf, _vsntprintf |
| StringCbLength | strlen |
Using Strsafe.h
To use the Strsafe functions inline, include the header file as shown here.
Important : The include line for strsafe.h should follow all other headers' include lines.
- To use the functions in library form, define STRSAFE_LIB before including the new header file as shown below, and then add a link in your project to $(SDK_LIB_PATH)\strsafe.lib.
|
#define STRSAFE_LIB
#include <strsafe.h> |
Note : StringCbGets, StringCbGetsEx, StringCchGets, and StringCchGetsEx must be run as inline functions.
When you include Strsafe.h in your file, the older functions replaced by the Strsafe.h functions will be deprecated. Attempts to use these older functions will result in a compiler error telling you to use the newer functions. If you want to override this behavior, include the following line in your code before including the Strsafe header file.
|
#define STRSAFE_NO_DEPRECATE |
To allow only character count functions, include the following line in your code before including the Strsafe header file.
|
#define STRSAFE_NO_CB_FUNCTIONS |
To allow only byte count functions, include the following line in your code before including the Strsafe header file.
|
#define STRSAFE_NO_CCH_FUNCTIONS |
Note : You can define STRSAFE_NO_CB_FUNCTIONS or STRSAFE_NO_CCH_FUNCTIONS, but not both.
The maximum supported string length is 2,147,483,647 (STRSAFE_MAX_CCH) characters, either ANSI or Unicode.