|
PROLOG | NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | APPLICATION USAGE | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT |
CONFSTR(3P) POSIX Programmer's Manual CONFSTR(3P)
This manual page is part of the POSIX Programmer's Manual. The Linux
implementation of this interface may differ (consult the
corresponding Linux manual page for details of Linux behavior), or
the interface may not be implemented on Linux.
confstr — get configurable variables
#include <unistd.h>
size_t confstr(int name, char *buf, size_t len);
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_V7_ILP32_OFF32_CFLAGS
_CS_POSIX_V7_ILP32_OFF32_LDFLAGS
_CS_POSIX_V7_ILP32_OFF32_LIBS
_CS_POSIX_V7_ILP32_OFFBIG_CFLAGS
_CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS
_CS_POSIX_V7_ILP32_OFFBIG_LIBS
_CS_POSIX_V7_LP64_OFF64_CFLAGS
_CS_POSIX_V7_LP64_OFF64_LDFLAGS
_CS_POSIX_V7_LP64_OFF64_LIBS
_CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS
_CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS
_CS_POSIX_V7_LPBIG_OFFBIG_LIBS
_CS_POSIX_V7_THREADS_CFLAGS
_CS_POSIX_V7_THREADS_LDFLAGS
_CS_POSIX_V7_WIDTH_RESTRICTED_ENVS
_CS_V7_ENV
_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
_CS_V6_ENV
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.
After a call to:
confstr(_CS_V7_ENV, buf, sizeof(buf))
the string stored in buf will contain the <space>-separated list of
variable=value environment variable pairs required by the
implementation to create a conforming environment, as described in
the implementations' conformance documentation.
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 POSIX.1‐2008, if the return value is
less than or equal to sizeof(buf).
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.
The confstr() function shall fail if:
EINVAL The value of the name argument is invalid.
The following sections are informative.
None.
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 POSIX.1‐2008, 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.
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 POSIX.1‐2008.
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.
None.
exec(1p), fpathconf(3p), sysconf(3p)
The Base Definitions volume of POSIX.1‐2008, unistd.h(0p)
The Shell and Utilities volume of POSIX.1‐2008, c99(1p)
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2013 Edition, Standard for Information
Technology -- Portable Operating System Interface (POSIX), The Open
Group Base Specifications Issue 7, Copyright (C) 2013 by the
Institute of Electrical and Electronics Engineers, Inc and The Open
Group. (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1
applied.) In the event of any discrepancy between this version and
the original IEEE and The Open Group Standard, the original IEEE and
The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.unix.org/online.html .
Any typographical or formatting errors that appear in this page are
most likely to have been introduced during the conversion of the
source files to man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2013 CONFSTR(3P)
Pages that refer to this page: poll.h(0p), stddef.h(0p), sys_types.h(0p), termios.h(0p), unistd.h(0p), wchar.h(0p), getconf(1p), exec(3p), fpathconf(3p), sysconf(3p)