1CONFSTR(P) POSIX Programmer's Manual CONFSTR(P)
2
6 confstr - get configurable variables
7
9 #include <unistd.h>
10 size_t confstr(int name, char *buf, size_t len);
12
15 The confstr() function shall return configuration-defined string val‐
16 ues. Its use and purpose are similar to sysconf(), but it is used where
17 string values rather than numeric values are returned.
18 The name argument represents the system variable to be queried. The
20 implementation shall support the following name values, defined in
21 <unistd.h>. It may support others:
22 _CS_PATH
24 _CS_POSIX_V6_ILP32_OFF32_CFLAGS
25 _CS_POSIX_V6_ILP32_OFF32_LDFLAGS
26 _CS_POSIX_V6_ILP32_OFF32_LIBS
27 _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS
28 _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS
29 _CS_POSIX_V6_ILP32_OFFBIG_LIBS
30 _CS_POSIX_V6_LP64_OFF64_CFLAGS
31 _CS_POSIX_V6_LP64_OFF64_LDFLAGS
32 _CS_POSIX_V6_LP64_OFF64_LIBS
33 _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS
34 _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS
35 _CS_POSIX_V6_LPBIG_OFFBIG_LIBS
36 _CS_POSIX_V6_WIDTH_RESTRICTED_ENVS
37 _CS_XBS5_ILP32_OFF32_CFLAGS (LEGACY)
39 _CS_XBS5_ILP32_OFF32_LDFLAGS (LEGACY)
40 _CS_XBS5_ILP32_OFF32_LIBS (LEGACY)
41 _CS_XBS5_ILP32_OFF32_LINTFLAGS (LEGACY)
42 _CS_XBS5_ILP32_OFFBIG_CFLAGS (LEGACY)
43 _CS_XBS5_ILP32_OFFBIG_LDFLAGS (LEGACY)
44 _CS_XBS5_ILP32_OFFBIG_LIBS (LEGACY)
45 _CS_XBS5_ILP32_OFFBIG_LINTFLAGS (LEGACY)
46 _CS_XBS5_LP64_OFF64_CFLAGS (LEGACY)
47 _CS_XBS5_LP64_OFF64_LDFLAGS (LEGACY)
48 _CS_XBS5_LP64_OFF64_LIBS (LEGACY)
49 _CS_XBS5_LP64_OFF64_LINTFLAGS (LEGACY)
50 _CS_XBS5_LPBIG_OFFBIG_CFLAGS (LEGACY)
51 _CS_XBS5_LPBIG_OFFBIG_LDFLAGS (LEGACY)
52 _CS_XBS5_LPBIG_OFFBIG_LIBS (LEGACY)
53 _CS_XBS5_LPBIG_OFFBIG_LINTFLAGS (LEGACY)
54 If len is not 0, and if name has a configuration-defined value, conf‐
57 str() shall copy that value into the len-byte buffer pointed to by buf.
58 If the string to be returned is longer than len bytes, including the
59 terminating null, then confstr() shall truncate the string to len-1
60 bytes and null-terminate the result. The application can detect that
61 the string was truncated by comparing the value returned by confstr()
62 with len.
63 If len is 0 and buf is a null pointer, then confstr() shall still
65 return the integer value as defined below, but shall not return a
66 string. If len is 0 but buf is not a null pointer, the result is
67 unspecified.
68 If the implementation supports the POSIX shell option, the string
70 stored in buf after a call to:
71 confstr(_CS_PATH, buf, sizeof(buf))
74 can be used as a value of the PATH environment variable that accesses
76 all of the standard utilities of IEEE Std 1003.1-2001, if the return
77 value is less than or equal to sizeof( buf).
78
80 If name has a configuration-defined value, confstr() shall return the
81 size of buffer that would be needed to hold the entire configuration-
82 defined value including the terminating null. If this return value is
83 greater than len, the string returned in buf is truncated.
84 If name is invalid, confstr() shall return 0 and set errno to indicate
86 the error.
87 If name does not have a configuration-defined value, confstr() shall
89 return 0 and leave errno unchanged.
90
92 The confstr() function shall fail if:
93 EINVAL The value of the name argument is invalid.
95 The following sections are informative.
98
100 None.
101
103 An application can distinguish between an invalid name parameter value
104 and one that corresponds to a configurable variable that has no config‐
105 uration-defined value by checking if errno is modified. This mirrors
106 the behavior of sysconf().
107 The original need for this function was to provide a way of finding the
109 configuration-defined default value for the environment variable PATH .
110 Since PATH can be modified by the user to include directories that
111 could contain utilities replacing the standard utilities in the Shell
112 and Utilities volume of IEEE Std 1003.1-2001, applications need a way
113 to determine the system-supplied PATH environment variable value that
114 contains the correct search path for the standard utilities.
115 An application could use:
117 confstr(name, (char *)NULL, (size_t)0)
120 to find out how big a buffer is needed for the string value; use mal‐
122 loc() to allocate a buffer to hold the string; and call confstr() again
123 to get the string. Alternately, it could allocate a fixed, static buf‐
124 fer that is big enough to hold most answers (perhaps 512 or 1024
125 bytes), but then use malloc() to allocate a larger buffer if it finds
126 that this is too small.
127
129 Application developers can normally determine any configuration vari‐
130 able by means of reading from the stream opened by a call to:
131 popen("command -p getconf variable", "r");
134 The confstr() function with a name argument of _CS_PATH returns a
136 string that can be used as a PATH environment variable setting that
137 will reference the standard shell and utilities as described in the
138 Shell and Utilities volume of IEEE Std 1003.1-2001.
139 The confstr() function copies the returned string into a buffer sup‐
141 plied by the application instead of returning a pointer to a string.
142 This allows a cleaner function in some implementations (such as those
143 with lightweight threads) and resolves questions about when the appli‐
144 cation must copy the string returned.
145
147 None.
148
150 pathconf() , sysconf() , the Base Definitions volume of
151 IEEE Std 1003.1-2001, <unistd.h>, the Shell and Utilities volume of
152 IEEE Std 1003.1-2001, c99
153
155 Portions of this text are reprinted and reproduced in electronic form
156 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
157 -- Portable Operating System Interface (POSIX), The Open Group Base
158 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
159 Electrical and Electronics Engineers, Inc and The Open Group. In the
160 event of any discrepancy between this version and the original IEEE and
161 The Open Group Standard, the original IEEE and The Open Group Standard
162 is the referee document. The original Standard can be obtained online
163 at http://www.opengroup.org/unix/online.html .
164IEEE/The Open Group 2003 CONFSTR(P)