The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group


confstr - get configurable variables


#include <unistd.h>

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


The confstr() function provides a method for applications to get configuration-defined string values. Its use and purpose are similar to sysconf(), but it is used where string values rather than numeric values are returned.

The name argument represents the system variable to be queried. The implementation supports the following name values, defined in <unistd.h>. It may support others:


If len is not 0, and if name has a configuration-defined value, confstr() copies that value into the len-byte buffer pointed to by buf. If the string to be returned is longer than len bytes, including the terminating null, then confstr() truncates the string to len-1 bytes and null-terminates the result. The application can detect that the string was truncated by comparing the value returned by confstr() with len.

If len is 0 and buf is a null pointer, then confstr() still returns the integer value as defined below, but does not return a string. If len is 0 but buf is not a null pointer, the result is unspecified.


If name has a configuration-defined value, confstr() returns the size of buffer that would be needed to hold the entire configuration-defined value including the terminating null. If this return value is greater than len, the string returned in buf is truncated.

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

If name does not have a configuration-defined value, confstr() returns 0 and leaves errno unchanged.


The confstr() function will fail if:
The value of the name argument is invalid.




An application can distinguish between an invalid name parameter value and one that corresponds to a configurable variable that has no configuration-defined value by checking if errno is modified. This mirrors the behaviour of sysconf().

The original need for this function was to provide a way of finding the configuration-defined default value for the environment variable PATH. Since PATH can be modified by the user to include directories that could contain utilities replacing XCU specification standard utilities, applications need a way to determine the system-supplied PATH environment variable value that contains the correct search path for the standard utilities.

An application could use:

confstr(name, (char *)NULL, (size_t)0)

to find out how big a buffer is needed for the string value; use malloc() to allocate a buffer to hold the string; and call confstr() again to get the string. Alternately, it could allocate a fixed, static buffer that is big enough to hold most answers (perhaps 512 or 1024 bytes), but then use malloc() to allocate a larger buffer if it finds that this is too small.




pathconf(), sysconf(), <unistd.h>, the XCU specification of getconf.


Derived from the ISO POSIX-2 standard.

UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]