confstr (original) (raw)

The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

A newer edition of this document exists here

NAME

confstr - get configurable variables

SYNOPSIS

`#include <unistd.h>

size_t confstr(int

name, char *buf, size_t len);
`

DESCRIPTION

The confstr() function shall return 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 shall support the following name values, defined in <unistd.h>. It may support others:

_CS_PATH
_CS_POSIX_V6_ILP32_OFF32_CFLAGS
_CS_POSIX_V6_ILP32_OFF32_LDFLAGS
_CS_POSIX_V6_ILP32_OFF32_LIBS
_CS_POSIX_V6_ILP32_OFFBIG_CFLAGS
_CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS
_CS_POSIX_V6_ILP32_OFFBIG_LIBS
_CS_POSIX_V6_LP64_OFF64_CFLAGS
_CS_POSIX_V6_LP64_OFF64_LDFLAGS
_CS_POSIX_V6_LP64_OFF64_LIBS
_CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS
_CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS
_CS_POSIX_V6_LPBIG_OFFBIG_LIBS
_CS_POSIX_V6_WIDTH_RESTRICTED_ENVS
[XSI]
_CS_XBS5_ILP32_OFF32_CFLAGS (LEGACY)
_CS_XBS5_ILP32_OFF32_LDFLAGS (LEGACY)
_CS_XBS5_ILP32_OFF32_LIBS (LEGACY)
_CS_XBS5_ILP32_OFF32_LINTFLAGS (LEGACY)
_CS_XBS5_ILP32_OFFBIG_CFLAGS (LEGACY)
_CS_XBS5_ILP32_OFFBIG_LDFLAGS (LEGACY)
_CS_XBS5_ILP32_OFFBIG_LIBS (LEGACY)
_CS_XBS5_ILP32_OFFBIG_LINTFLAGS (LEGACY)
_CS_XBS5_LP64_OFF64_CFLAGS (LEGACY)
_CS_XBS5_LP64_OFF64_LDFLAGS (LEGACY)
_CS_XBS5_LP64_OFF64_LIBS (LEGACY)
_CS_XBS5_LP64_OFF64_LINTFLAGS (LEGACY)
_CS_XBS5_LPBIG_OFFBIG_CFLAGS (LEGACY)
_CS_XBS5_LPBIG_OFFBIG_LDFLAGS (LEGACY)
_CS_XBS5_LPBIG_OFFBIG_LIBS (LEGACY)
_CS_XBS5_LPBIG_OFFBIG_LINTFLAGS (LEGACY)

If len is not 0, and if name has a configuration-defined value, confstr() shall copy 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() shall truncate the string to _len_-1 bytes and null-terminate 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() shall still return the integer value as defined below, but shall not return a string. If len is 0 but buf is not a null pointer, the result is unspecified.

If the implementation supports the POSIX shell option, the string stored in buf after a call to:

confstr(_CS_PATH, buf, sizeof(buf))

can be used as a value of the PATH environment variable that accesses all of the standard utilities of IEEE Std 1003.1-2001, if the return value is less than or equal to sizeof( buf).

RETURN VALUE

If name has a configuration-defined value, confstr() shall return 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() shall return 0 and set errno to indicate the error.

If name does not have a configuration-defined value, confstr() shall return 0 and leave _errno_unchanged.

ERRORS

The confstr() function shall fail if:

[EINVAL]

The value of the name argument is invalid.

The following sections are informative.

EXAMPLES

None.

APPLICATION USAGE

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 behavior 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 the standard utilities in the Shell and Utilities volume of IEEE Std 1003.1-2001, 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.

RATIONALE

Application developers can normally determine any configuration variable by means of reading from the stream opened by a call to:

popen("command -p getconf variable", "r");

The confstr() function with a name argument of _CS_PATH returns a string that can be used as a _PATH_environment variable setting that will reference the standard shell and utilities as described in the Shell and Utilities volume of IEEE Std 1003.1-2001.

The confstr() function copies the returned string into a buffer supplied by the application instead of returning a pointer to a string. This allows a cleaner function in some implementations (such as those with lightweight threads) and resolves questions about when the application must copy the string returned.

FUTURE DIRECTIONS

None.

CHANGE HISTORY

First released in Issue 4. Derived from the ISO POSIX-2 standard.

Issue 5

A table indicating the permissible values of name is added to the DESCRIPTION. All those marked EX are new in this issue.

Issue 6

The Open Group Corrigendum U033/7 is applied. The return value for the case returning the size of the buffer now explicitly states that this includes the terminating null.

The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:

The DESCRIPTION is updated with new arguments which can be used to determine configuration strings for C compiler flags, linker/loader flags, and libraries for each different supported programming environment. This is a change to support data size neutrality.

The following changes were made to align with the IEEE P1003.1a draft standard:

The DESCRIPTION is updated to include text describing how _CS_PATH can be used to obtain a PATH to access the standard utilities.

The macros associated with the c89 programming models are marked LEGACY and new equivalent macros associated with c99 are introduced.

End of informative text.

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT]