path: root/upstream/archlinux/man3p/confstr.3p

'\" et
.TH CONFSTR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
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.
.\"
.SH NAME
confstr
\(em get configurable variables
.SH SYNOPSIS
.LP
.nf
#include <unistd.h>
.P
size_t confstr(int \fIname\fP, char *\fIbuf\fP, size_t \fIlen\fP);
.fi
.SH DESCRIPTION
The
\fIconfstr\fR()
function shall return configuration-defined string values. Its use and
purpose are similar to
\fIsysconf\fR(),
but it is used where string values rather than numeric values are
returned.
.P
The
.IR name
argument represents the system variable to be queried. The
implementation shall support the following name values, defined in
.IR <unistd.h> .
It may support others:
.P
.nf
_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
.fi
.P
If
.IR len
is not 0, and if
.IR name
has a configuration-defined value,
\fIconfstr\fR()
shall copy that value into the
.IR len -byte
buffer pointed to by
.IR buf .
If the string to be returned is longer than
.IR len
bytes, including the terminating null, then
\fIconfstr\fR()
shall truncate the string to
.IR len \-1
bytes and null-terminate the result. The application can detect that
the string was truncated by comparing the value returned by
\fIconfstr\fR()
with
.IR len .
.P
If
.IR len
is 0 and
.IR buf
is a null pointer, then
\fIconfstr\fR()
shall still return the integer value as defined below, but shall not
return a string. If
.IR len
is 0 but
.IR buf
is not a null pointer, the result is unspecified.
.P
After a call to:
.sp
.RS 4
.nf

confstr(_CS_V7_ENV, buf, sizeof(buf))
.fi
.P
.RE
.P
the string stored in
.IR buf
shall contain a
<space>-separated
list of the variable=value environment variable pairs an
implementation requires as part of specifying a conforming
environment, as described in the implementations' conformance
documentation.
.P
If the implementation supports the POSIX shell option, the string
stored in
.IR buf
after a call to:
.sp
.RS 4
.nf

confstr(_CS_PATH, buf, sizeof(buf))
.fi
.P
.RE
.P
can be used as a value of the
.IR PATH
environment variable that accesses all of the standard utilities of
POSIX.1\(hy2008, that are provided in a manner accessible via the
.IR exec
family of functions, if the return value is less than or equal to
.IR sizeof (\c
.IR buf ).
.SH "RETURN VALUE"
If
.IR name
has a configuration-defined value,
\fIconfstr\fR()
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
.IR len ,
the string returned in
.IR buf
is truncated.
.P
If
.IR name
is invalid,
\fIconfstr\fR()
shall return 0 and set
.IR errno
to indicate the error.
.P
If
.IR name
does not have a configuration-defined value,
\fIconfstr\fR()
shall return 0 and leave
.IR errno
unchanged.
.SH ERRORS
The
\fIconfstr\fR()
function shall fail if:
.TP
.BR EINVAL
The value of the
.IR name
argument is invalid.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
An application can distinguish between an invalid
.IR name
parameter value and one that corresponds to a configurable variable
that has no configuration-defined value by checking if
.IR errno
is modified. This mirrors the behavior of
\fIsysconf\fR().
.P
The original need for this function was to provide a way of finding the
configuration-defined default value for the environment variable
.IR PATH .
Since
.IR 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\(hy2017, applications
need a way to determine the system-supplied
.IR PATH
environment variable value that contains the correct search path for
the standard utilities.
.P
An application could use:
.sp
.RS 4
.nf

confstr(name, (char *)NULL, (size_t)0)
.fi
.P
.RE
.P
to find out how big a buffer is needed for the string value; use
\fImalloc\fR()
to allocate a buffer to hold the string; and call
\fIconfstr\fR()
again to get the string. Alternately, it could allocate a fixed, static
buffer that is big enough to hold most answers (perhaps 512 or 1\|024
bytes), but then use
\fImalloc\fR()
to allocate a larger buffer if it finds that this is too small.
.SH RATIONALE
Application developers can normally determine any configuration
variable by means of reading from the stream opened by a call to:
.sp
.RS 4
.nf

popen("command -p getconf variable", "r");
.fi
.P
.RE
.P
The
\fIconfstr\fR()
function with a
.IR name
argument of _CS_PATH returns a string that can be used as a
.IR PATH
environment variable setting that will reference the standard shell and
utilities as described in the Shell and Utilities volume of POSIX.1\(hy2017.
.P
The
\fIconfstr\fR()
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"
None.
.SH "SEE ALSO"
.IR "\fIexec\fR\^",
.IR "\fIfpathconf\fR\^(\|)",
.IR "\fIsysconf\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<unistd.h>\fP"
.P
The Shell and Utilities volume of POSIX.1\(hy2017,
.IR "\fIc99\fR\^"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 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 .
.PP
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 .