String Annotations

Null-terminated strings in C represent a special case of buffers. The following annotations describe null-terminated strings:

__nullterminated
__nullnullterminated
__possibly_notnullterminated

String annotations are useful when applied to typedef declarations. These annotations enable PFD to confirm that the type is used correctly in a function without requiring the programmer to annotate every function parameter that uses the type.

Note   The examples in this section are intended only to show the use of annotations for null-terminated strings. Always use the safe string functions declared in Ntstrsafe.h for string and UNICODE_STRING manipulations instead of writing your own string manipulation functions.

• __nullterminated
  Many of the types declared in system header files are usually already annotated. If you use the appropriate STR type for all functions that take strings described as char * or wchar_t * parameters, it is not necessary to apply the __nullterminated annotations to these types. PSTR, PCSTR, and their "L" and "W" variations all imply that a string is null terminated. You should explicitly apply __nullterminated only to types that are not already annotated with __nullterminated.

  The implied use of __nullterminated when you use PSTR or PCSTR types is sufficient for input string buffers. If the parameter is strictly for input, use the CSTR forms because placement of the const modifier must be done inside the typedef.

  If a function can create or add to a string, the function must have the actual size of the output buffer so it does not overrun it. Output buffers should also have an additional count annotation--_ecount or _bcount--that gives the actual buffer size because __nullterminated by itself does not provide that information. For __out parameters, the count annotation specifies that the resulting string is null terminated and that PFD should check for buffer overruns. For __inout parameters, the count annotation implies that the buffer is initialized up to the NULL and that the updated value is also null terminated.

  For example, the StringCchCopyA function copies up to cchDest elements. The __out_ecount annotation specifies that although the string is null terminated--as indicated by the LPSTR type--it does not overflow cchDest bytes, as shown in the following example:

  StringCchCopyA(
      __out_ecount(cchDest) LPSTR pszDest,
      __in size_t cchDest,
      __in LPCSTR pszSrc);
  

• __nullnullterminated
  The __nullnullterminated annotation is intended for the occasional "string of strings" that is terminated by a double null, such as a registry value whose type is REG_MULTI_SZ. Currently, PFD does not check __nullnullterminated, so this annotation should be considered advisory only. However, __nullnullterminated might be enabled in a future version of PFD. In the meantime, use a #pragma warning directive or the _xcount annotation to silence PFD noise that is related to strings terminated with a double null.

• __possibly_notnullterminated
  Several older functions usually return null-terminated strings but occasionally do not. The classic examples are snprintf and strncpy, where the function omits the null terminator if the buffer is exactly full. These two functions are considered deprecated and should not be used. Instead, use the equivalent functions declared in StrSafe.h for user-mode applications or NtStrSafe.h for kernel-mode code because they guarantee a null-terminated buffer on success.

  Despite the deprecation, it might not be possible to completely eliminate functions that omit the null terminator in existing code, so make sure to annotate these functions in existing code by applying __possibly_notnullterminated to their output parameters, as shown in the following example:

  int _snprintf(
     __out_ecount(count) __possibly_notnullterminated LPSTR buffer,
     __in size_t count,
     __in LPCSTR *format
     [, argument] ...
  );
  

  When PFD encounters a __possibly_notnullterminated annotation, it attempts to determine whether an action was taken to assure null termination of the output string. If it cannot find one, PFD generates a warning.

 

 

Send comments about this topic to Microsoft

Build date: 5/3/2011