About Strsafe.h

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 Windows implementations. Strsafe.h is available in the Windows SDK starting with Windows XP with Service Pack 2 (SP2).

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 value, 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.

Character Count Functions

The following functions use a character count rather than a byte count.

Function Replaces
StringCchCat
StringCchCatEx
strcat, wcscat, _tcsat
lstrcat
StrCat
StrCatBuff
StringCchCatN
StringCchCatNEx
strncat
StrNCat
StringCchCopy
StringCchCopyEx
strcpy, wcscpy, _tcscpy
lstrcpy
StrCpy
StringCchCopyN
StringCchCopyNEx
strncpy, wcsncpy, _tcsncpy
StringCchGets
StringCchGetsEx
gets, _getws, _getts
StringCchPrintf
StringCchPrintfEx
sprintf, swprintf, _stprintf
wsprintf
wnsprintf
_snprintf, _snwprintf, _sntprintf
StringCchVPrintf
StringCchVPrintfEx
vsprintf, vswprintf, _vstprintf
vsnprintf, _vsnwprintf, _vsntprintf
wvsprintf
wvnsprintf
,
StringCchLength
strlen, wcslen, _tcslen

 

Byte Count Functions

The following functions use a byte count rather than a character count.

Function Replaces
StringCbCat
StringCbCatEx
strcat, wcscat, _tcsat
lstrcat
StrCat
StrCatBuff
StringCbCatN
StringCbCatNEx
strncat
StrNCat
StringCbCopy
StringCbCopyEx
strcpy, wcscpy, _tcscpy
lstrcpy
StrCpy
StringCbCopyN
StringCbCopyNEx
strncpy, wcsncpy, _tcsncpy
StringCbGets
StringCbGetsEx
gets, _getws, _getts
StringCbPrintf
StringCbPrintfEx
sprintf, swprintf, _stprintf
wsprintf
wnsprintf
_snprintf, _snwprintf, _sntprintf
StringCbVPrintf
StringCbVPrintfEx
vsprintf, vswprintf, _vstprintf
vsnprintf, _vsnwprintf, _vsntprintf
wvsprintf
wvnsprintf
StringCbLength
strlen, wcslen, _tcslen

 

Using Strsafe.h

  • To use the Strsafe functions inline, include the header file as shown here, following the #include statements for all other header files.

    #include <strsafe.h>

  • To use the functions in library form, include the following statement before including Strsafe.h. However, it is recommended that you use the inline functions.

    #define STRSAFE_LIB

    Note

    : The following functions must be used as inline functions: StringCbGets, StringCbGetsEx, StringCchGets, and StringCchGetsEx.

     

  • 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 statement before including Strsafe.h.

    #define STRSAFE_NO_DEPRECATE

  • To allow only character count functions, include the following statement before including Strsafe.h.

    #define STRSAFE_NO_CB_FUNCTIONS

  • To allow only byte count functions, include the following statement before including Strsafe.h.

    #define STRSAFE_NO_CCH_FUNCTIONS

    Note

    You can define STRSAFE_NO_CB_FUNCTIONS or STRSAFE_NO_CCH_FUNCTIONS, but not both.

     

  • Some Strsafe functions have locale-aware versions. By default, the header does not declare these functions. To enable these declarations, include the following macro statement before including Strsafe.h.

    #define STRSAFE_LOCALE_FUNCTIONS

  • The maximum supported string length is 2,147,483,647 (STRSAFE_MAX_CCH) characters, either ANSI or Unicode.

Strsafe Functions