WritePrivateProfileString

3.0

The WritePrivateProfileString function copies a character string into the specified section of the specified initialization file.

Parameters

lpszSection

Points to a null-terminated string that specifies the section to which the string will be copied. If the section does not exist, it is created. The name of the section is case-independent; the string may be any combination of uppercase and lowercase letters.

lpszEntry

Points to the null-terminated string containing the entry to be associated with the string. If the entry does not exist in the specified section, it is created. If this parameter is NULL, the entire section, including all entries within the section, is deleted.

lpszString

Points to the null-terminated string to be written to the file. If this parameter is NULL, the entry specified by the lpszEntry parameter is deleted.

lpszFilename

Points to a null-terminated string that names the initialization file.

Return Value

The return value is nonzero if the function is successful. Otherwise, it is zero.

Comments

To improve performance, Windows keeps a cached version of the most-recently accessed initialization file. If that filename is specified and the other three parameters are NULL, Windows flushes the cache.

Sections in the initialization file have the following form:

[section]
entry=string
.
.
.

If lpszFilename does not contain a fully qualified path and filename for the file, WritePrivateProfileString searches the Windows directory for the file. If the file does not exist, this function creates the file in the Windows directory.

If lpszFilename contains a fully qualified path and filename and the file does not exist, this function creates the file. The specified directory must already exist.

An application should use a private (application-specific) initialization file to record information that affects only that application. This improves the performance of both the application and Windows itself by reducing the amount of information that Windows must read when it accesses the initialization file. The exception to this is that device drivers should use the SYSTEM.INI file, to reduce the number of initialization files Windows must open and read during the startup process.

An application can use the WriteProfileString function to add a string to the WIN.INI file.

Example

The following example uses the WritePrivateProfileString function to add the string “testcode.c” to the LastFile entry in the [MyApp] section of the TESTCODE.INI initialization file:

BOOL fSuccess;

DebugBreak();

fSuccess = WritePrivateProfileString("MyApp",
    "LastFile", "testcode.c", "testcode.ini");

if (fSuccess)
    MessageBox(hwnd, "String added successfully",
            "WritePrivateProfileString", MB_OK);
else
    MessageBox(hwnd, "String could not be added",
            "WritePrivateProfileString", MB_ICONSTOP);

See Also

WriteProfileString