1CONFSTR(3P) POSIX Programmer's Manual CONFSTR(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 confstr — get configurable variables
13
15 #include <unistd.h>
16 size_t confstr(int name, char *buf, size_t len);
18
20 The confstr() function shall return configuration-defined string val‐
21 ues. Its use and purpose are similar to sysconf(), but it is used where
22 string values rather than numeric values are returned.
23 The name argument represents the system variable to be queried. The
25 implementation shall support the following name values, defined in
26 <unistd.h>. It may support others:
27 _CS_PATH
29 _CS_POSIX_V7_ILP32_OFF32_CFLAGS
30 _CS_POSIX_V7_ILP32_OFF32_LDFLAGS
31 _CS_POSIX_V7_ILP32_OFF32_LIBS
32 _CS_POSIX_V7_ILP32_OFFBIG_CFLAGS
33 _CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS
34 _CS_POSIX_V7_ILP32_OFFBIG_LIBS
35 _CS_POSIX_V7_LP64_OFF64_CFLAGS
36 _CS_POSIX_V7_LP64_OFF64_LDFLAGS
37 _CS_POSIX_V7_LP64_OFF64_LIBS
38 _CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS
39 _CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS
40 _CS_POSIX_V7_LPBIG_OFFBIG_LIBS
41 _CS_POSIX_V7_THREADS_CFLAGS
42 _CS_POSIX_V7_THREADS_LDFLAGS
43 _CS_POSIX_V7_WIDTH_RESTRICTED_ENVS
44 _CS_V7_ENV
45 _CS_POSIX_V6_ILP32_OFF32_CFLAGS
46 _CS_POSIX_V6_ILP32_OFF32_LDFLAGS
47 _CS_POSIX_V6_ILP32_OFF32_LIBS
48 _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS
49 _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS
50 _CS_POSIX_V6_ILP32_OFFBIG_LIBS
51 _CS_POSIX_V6_LP64_OFF64_CFLAGS
52 _CS_POSIX_V6_LP64_OFF64_LDFLAGS
53 _CS_POSIX_V6_LP64_OFF64_LIBS
54 _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS
55 _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS
56 _CS_POSIX_V6_LPBIG_OFFBIG_LIBS
57 _CS_POSIX_V6_WIDTH_RESTRICTED_ENVS
58 _CS_V6_ENV
59 If len is not 0, and if name has a configuration-defined value, conf‐
61 str() shall copy that value into the len-byte buffer pointed to by buf.
62 If the string to be returned is longer than len bytes, including the
63 terminating null, then confstr() shall truncate the string to len-1
64 bytes and null-terminate the result. The application can detect that
65 the string was truncated by comparing the value returned by confstr()
66 with len.
67 If len is 0 and buf is a null pointer, then confstr() shall still
69 return the integer value as defined below, but shall not return a
70 string. If len is 0 but buf is not a null pointer, the result is
71 unspecified.
72 After a call to:
74 confstr(_CS_V7_ENV, buf, sizeof(buf))
77 the string stored in buf shall contain a <space>-separated list of the
79 variable=value environment variable pairs an implementation requires as
80 part of specifying a conforming environment, as described in the imple‐
81 mentations' conformance documentation.
82 If the implementation supports the POSIX shell option, the string
84 stored in buf after a call to:
85 confstr(_CS_PATH, buf, sizeof(buf))
88 can be used as a value of the PATH environment variable that accesses
90 all of the standard utilities of POSIX.1‐2008, that are provided in a
91 manner accessible via the exec family of functions, if the return value
92 is less than or equal to sizeof(buf).
93
95 If name has a configuration-defined value, confstr() shall return the
96 size of buffer that would be needed to hold the entire configuration-
97 defined value including the terminating null. If this return value is
98 greater than len, the string returned in buf is truncated.
99 If name is invalid, confstr() shall return 0 and set errno to indicate
101 the error.
102 If name does not have a configuration-defined value, confstr() shall
104 return 0 and leave errno unchanged.
105
107 The confstr() function shall fail if:
108 EINVAL The value of the name argument is invalid.
110 The following sections are informative.
112
114 None.
115
117 An application can distinguish between an invalid name parameter value
118 and one that corresponds to a configurable variable that has no config‐
119 uration-defined value by checking if errno is modified. This mirrors
120 the behavior of sysconf().
121 The original need for this function was to provide a way of finding the
123 configuration-defined default value for the environment variable PATH.
124 Since PATH can be modified by the user to include directories that
125 could contain utilities replacing the standard utilities in the Shell
126 and Utilities volume of POSIX.1‐2017, applications need a way to deter‐
127 mine the system-supplied PATH environment variable value that contains
128 the correct search path for the standard utilities.
129 An application could use:
131 confstr(name, (char *)NULL, (size_t)0)
134 to find out how big a buffer is needed for the string value; use mal‐
136 loc() to allocate a buffer to hold the string; and call confstr() again
137 to get the string. Alternately, it could allocate a fixed, static buf‐
138 fer that is big enough to hold most answers (perhaps 512 or 1024
139 bytes), but then use malloc() to allocate a larger buffer if it finds
140 that this is too small.
141
143 Application developers can normally determine any configuration vari‐
144 able by means of reading from the stream opened by a call to:
145 popen("command -p getconf variable", "r");
148 The confstr() function with a name argument of _CS_PATH returns a
150 string that can be used as a PATH environment variable setting that
151 will reference the standard shell and utilities as described in the
152 Shell and Utilities volume of POSIX.1‐2017.
153 The confstr() function copies the returned string into a buffer sup‐
155 plied by the application instead of returning a pointer to a string.
156 This allows a cleaner function in some implementations (such as those
157 with lightweight threads) and resolves questions about when the appli‐
158 cation must copy the string returned.
159
161 None.
162
164 exec, fpathconf(), sysconf()
165 The Base Definitions volume of POSIX.1‐2017, <unistd.h>
167 The Shell and Utilities volume of POSIX.1‐2017, c99
169
171 Portions of this text are reprinted and reproduced in electronic form
172 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
173 table Operating System Interface (POSIX), The Open Group Base Specifi‐
174 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
175 Electrical and Electronics Engineers, Inc and The Open Group. In the
176 event of any discrepancy between this version and the original IEEE and
177 The Open Group Standard, the original IEEE and The Open Group Standard
178 is the referee document. The original Standard can be obtained online
179 at http://www.opengroup.org/unix/online.html .
180 Any typographical or formatting errors that appear in this page are
182 most likely to have been introduced during the conversion of the source
183 files to man page format. To report such errors, see https://www.ker‐
184 nel.org/doc/man-pages/reporting_bugs.html .
185IEEE/The Open Group 2017 CONFSTR(3P)