IsBadStringPtr

The IsBadStringPtr function verifies that the calling process has read access to a range of memory pointed to by a string pointer.

BOOL IsBadStringPtr(
  LPCTSTR lpsz,      // string
  UINT_PTR ucchMax   // maximum size of string
);

Parameters

lpsz

[in] Pointer to a null-terminated string, either Unicode or ASCII.

ucchMax

[in] Specifies the maximum size, in TCHARs, of the string. The function checks for read access in all bytes up to the string's terminating null character or up to the number of bytes specified by this parameter, whichever is smaller. If this parameter is zero, the return value is zero.

Return Values

If the calling process has read access to all characters up to the string's terminating null character or up to the number of characters specified by ucchMax, the return value is zero.

If the calling process does not have read access to all characters up to the string's terminating null character or up to the number of characters specified by ucchMax, the return value is nonzero.

If the application is compiled as a debugging version, and the process does not have read access to the entire memory range specified, the function causes an assertion and breaks into the debugger. Leaving the debugger, the function continues as usual, and returns a nonzero value This behavior is by design, as a debugging aid.

Remarks

If the calling process has read access to some, but not all, of the specified memory range, the return value is nonzero.

In a preemptive multitasking environment, it is possible for some other thread to change the process's access to the memory being tested. Even when the function indicates that the process has read access to the specified memory, you should use structured exception handling when attempting to access the memory. Use of structured exception handling enables the system to notify the process if an access violation exception occurs, giving the process an opportunity to handle the exception.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Memory Management Overview, Memory Management Functions, IsBadCodePtr, IsBadReadPtr, IsBadWritePtr