[This is preliminary documentation and subject to change.]
Retrieves a string from the specified section in an initialization file.
null
, the GetPrivateProfileString function copies all section names in the file to the supplied buffer.null
, all key names in the section specified by the sectionName parameter are copied to the buffer specified by the value parameter.null
, the default is an empty string, ""
. Avoid specifying a default string with trailing blank characters. The function inserts a null
character in the value buffer to strip any trailing blanks.The return value is the number of characters copied to the buffer, not including the terminating null
character. If neither sectionName nor keyName is null
and the supplied destination buffer is too small to hold the requested string, the string is truncated and followed by a null
character, and the return value is equal to size minus one. If either sectionName or keyName is null
and the supplied destination buffer is too small to hold all the strings, the last string is truncated and followed by two null
characters. In this case, the return value is equal to size minus two. In the event the initialization file specified by fileName is not found, or contains invalid values, this function will set errorno with a value of '0x2' (File Not Found). To retrieve extended error information, call GetLastError.