confstr.3p (7256B)
- '\" 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 .