.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved .TH "CONFSTR" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" .\" confstr .SH NAME confstr \- get configurable variables .SH SYNOPSIS .LP \fB#include .br .sp size_t confstr(int\fP \fIname\fP\fB, char *\fP\fIbuf\fP\fB, size_t\fP \fIlen\fP\fB); .br \fP .SH DESCRIPTION .LP The \fIconfstr\fP() function shall return configuration-defined string values. Its use and purpose are similar to \fIsysconf\fP(), but it is used where string values rather than numeric values are returned. .LP The \fIname\fP argument represents the system variable to be queried. The implementation shall support the following name values, defined in \fI\fP. It may support others: .LP .sp _CS_PATH .br _CS_POSIX_V6_ILP32_OFF32_CFLAGS .br _CS_POSIX_V6_ILP32_OFF32_LDFLAGS .br _CS_POSIX_V6_ILP32_OFF32_LIBS .br _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS .br _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS .br _CS_POSIX_V6_ILP32_OFFBIG_LIBS .br _CS_POSIX_V6_LP64_OFF64_CFLAGS .br _CS_POSIX_V6_LP64_OFF64_LDFLAGS .br _CS_POSIX_V6_LP64_OFF64_LIBS .br _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS .br _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS .br _CS_POSIX_V6_LPBIG_OFFBIG_LIBS .br _CS_POSIX_V6_WIDTH_RESTRICTED_ENVS .br .sp _CS_XBS5_ILP32_OFF32_CFLAGS (\fBLEGACY\fP) .br _CS_XBS5_ILP32_OFF32_LDFLAGS (\fBLEGACY\fP) .br _CS_XBS5_ILP32_OFF32_LIBS (\fBLEGACY\fP) .br _CS_XBS5_ILP32_OFF32_LINTFLAGS (\fBLEGACY\fP) .br _CS_XBS5_ILP32_OFFBIG_CFLAGS (\fBLEGACY\fP) .br _CS_XBS5_ILP32_OFFBIG_LDFLAGS (\fBLEGACY\fP) .br _CS_XBS5_ILP32_OFFBIG_LIBS (\fBLEGACY\fP) .br _CS_XBS5_ILP32_OFFBIG_LINTFLAGS (\fBLEGACY\fP) .br _CS_XBS5_LP64_OFF64_CFLAGS (\fBLEGACY\fP) .br _CS_XBS5_LP64_OFF64_LDFLAGS (\fBLEGACY\fP) .br _CS_XBS5_LP64_OFF64_LIBS (\fBLEGACY\fP) .br _CS_XBS5_LP64_OFF64_LINTFLAGS (\fBLEGACY\fP) .br _CS_XBS5_LPBIG_OFFBIG_CFLAGS (\fBLEGACY\fP) .br _CS_XBS5_LPBIG_OFFBIG_LDFLAGS (\fBLEGACY\fP) .br _CS_XBS5_LPBIG_OFFBIG_LIBS (\fBLEGACY\fP) .br _CS_XBS5_LPBIG_OFFBIG_LINTFLAGS (\fBLEGACY\fP) .br .sp .LP If \fIlen\fP is not 0, and if \fIname\fP has a configuration-defined value, \fIconfstr\fP() shall copy that value into the \fIlen\fP-byte buffer pointed to by \fIbuf\fP. If the string to be returned is longer than \fIlen\fP bytes, including the terminating null, then \fIconfstr\fP() shall truncate the string to \fIlen\fP-1 bytes and null-terminate the result. The application can detect that the string was truncated by comparing the value returned by \fIconfstr\fP() with \fIlen\fP. .LP If \fIlen\fP is 0 and \fIbuf\fP is a null pointer, then \fIconfstr\fP() shall still return the integer value as defined below, but shall not return a string. If \fIlen\fP is 0 but \fIbuf\fP is not a null pointer, the result is unspecified. .LP If the implementation supports the POSIX shell option, the string stored in \fIbuf\fP after a call to: .sp .RS .nf \fBconfstr(_CS_PATH, buf, sizeof(buf)) \fP .fi .RE .LP can be used as a value of the \fIPATH\fP 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 \fIsizeof\fP( \fIbuf\fP). .SH RETURN VALUE .LP If \fIname\fP has a configuration-defined value, \fIconfstr\fP() 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 \fIlen\fP, the string returned in \fIbuf\fP is truncated. .LP If \fIname\fP is invalid, \fIconfstr\fP() shall return 0 and set \fIerrno\fP to indicate the error. .LP If \fIname\fP does not have a configuration-defined value, \fIconfstr\fP() shall return 0 and leave \fIerrno\fP unchanged. .SH ERRORS .LP The \fIconfstr\fP() function shall fail if: .TP 7 .B EINVAL The value of the \fIname\fP argument is invalid. .sp .LP \fIThe following sections are informative.\fP .SH EXAMPLES .LP None. .SH APPLICATION USAGE .LP An application can distinguish between an invalid \fIname\fP parameter value and one that corresponds to a configurable variable that has no configuration-defined value by checking if \fIerrno\fP is modified. This mirrors the behavior of \fIsysconf\fP(). .LP The original need for this function was to provide a way of finding the configuration-defined default value for the environment variable \fIPATH .\fP Since \fIPATH\fP 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 \fIPATH\fP environment variable value that contains the correct search path for the standard utilities. .LP An application could use: .sp .RS .nf \fBconfstr(name, (char *)NULL, (size_t)0) \fP .fi .RE .LP to find out how big a buffer is needed for the string value; use \fImalloc\fP() to allocate a buffer to hold the string; and call \fIconfstr\fP() 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 \fImalloc\fP() to allocate a larger buffer if it finds that this is too small. .SH RATIONALE .LP Application developers can normally determine any configuration variable by means of reading from the stream opened by a call to: .sp .RS .nf \fBpopen("command -p getconf variable", "r"); \fP .fi .RE .LP The \fIconfstr\fP() function with a \fIname\fP argument of _CS_PATH returns a string that can be used as a \fIPATH\fP 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. .LP The \fIconfstr\fP() 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. .SH FUTURE DIRECTIONS .LP None. .SH SEE ALSO .LP \fIpathconf\fP() , \fIsysconf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI\fP, the Shell and Utilities volume of IEEE\ Std\ 1003.1-2001, \fIc99\fP .SH COPYRIGHT Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html .