path: root/man3p/confstr.3p

.\" 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 <unistd.h>
.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<unistd.h>\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<unistd.h>\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 .