confstr(S)

confstr -- get configurable variables

Syntax

cc ... -lc

#include <unistd.h>

size_t confstr(int name, char *buf, size_t len);

Description

confstr(S) queries the system and determines the system default, i.e., configuration-defined, string values for system variables. It is similar to sysconf(S) in its use and purposes, except that a string value is returned by confstr( ).

The system variables are queried through their values, name. One such value is _CS_PATH, defined in <unistd.h>. This value may be used to query the system default for the PATH environmental variable. The buffer, buf, is used to hold the result of the query. If a user has modified PATH to include some personal directories, this routine may be used to find the system default for PATH.

If len is not zero and if the system variable, whose value is name, has a defined value, confstr( ) copies this configuration-defined string value to the buffer pointed by buf. The buffer should be at least len-byte in size. If the string to be copied, including the terminating null character, is longer than len bytes, only the first len-1 bytes will be copied to the buffer and the result is then null-terminated.

If len is zero and buf is a null pointer, confstr( ) does not copy the string but still returns the size of the string. This feature can be used to determine the buffer size dynamically, as in:

   buf_size = confstr(name , (char *) NULL, (size_t) 0);

and to call confstr( ) again to get the string after a proper buffer has been set up.

If len is zero and buf is not a null pointer, the result is unspecified.

Return values

If the system variable corresponding to name has a configuration-defined string value, confstr( ) returns the length of the string.

If name is invalid, confstr( ) returns zero and sets errno to indicate the error.

If the variable corresponding to name does not have a default string value on the system, confstr( ) returns zero without changing errno.

Diagnostics

If the required buffer size returned by confstr( ) is greater than len, the string returned in buf is truncated.

confstr( ) will fail if:

[EINVAL]: The value of the name argument is invalid.

By checking whether errno is modified, an application can distinguish between an invalid name parameter value and one corresponding to a configurable variable but without a configuration-defined value.

Standards conformance