Geoff Chappell - Software Analyst
This function copies as much of an input string as will fit in an output buffer, and ensures the output is null-terminated.
LPTSTR StrCpyNX (LPTSTR psz1, LPCTSTR psz2, int cchMax);
The function exists in both ANSI and Unicode forms.
The psz1 argument is the address of an output buffer that is to receive as large a copy as possible of the input string.
The psz2 argument is the address of the input string, or is NULL to stand for an empty input string.
The cchMax argument is the capacity of the output buffer, in characters.
If the function stores a string in the output buffer, it returns the address of the null terminator in the output string. Otherwise, function returns psz1.
If the output buffer’s capacity is not greater than zero, the function has nothing to do, and just returns psz1.
If no input string is given, the function stores a null character in the output buffer and is done. Otherwise, the function copies characters one by one from the input string to the output buffer up to and including a terminating null or until the output buffer is filled to one less than its capacity. The function then null-terminates the output (redundantly in the case where it has just copied a terminating null). The merit to the return value is apparent if the next step is to append a string to the output.
The behaviour is perhaps better treated as undefined if the input string overlaps the output buffer: the copy will be correct if the source is higher in memory than the destination, but the source may be corrupted.
The StrCpyNX function is exported from SHLWAPI.DLL as ordinals 399 and 400 (for ANSI and Unicode forms respectively) in version 5.0 and higher.
Though this function dates from as long ago as 1999, it was still not documented by Microsoft as late as the January 2007 edition of the Windows Vista Software Development Kit (SDK).