1CONFSTR(3P)                POSIX Programmer's Manual               CONFSTR(3P)
2
3
4

PROLOG

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
11

NAME

13       confstr — get configurable variables
14

SYNOPSIS

16       #include <unistd.h>
17
18       size_t confstr(int name, char *buf, size_t len);
19

DESCRIPTION

21       The confstr() function shall return configuration-defined  string  val‐
22       ues. Its use and purpose are similar to sysconf(), but it is used where
23       string values rather than numeric values are returned.
24
25       The name argument represents the system variable  to  be  queried.  The
26       implementation  shall  support  the  following  name values, defined in
27       <unistd.h>.  It may support others:
28
29       _CS_PATH
30       _CS_POSIX_V7_ILP32_OFF32_CFLAGS
31       _CS_POSIX_V7_ILP32_OFF32_LDFLAGS
32       _CS_POSIX_V7_ILP32_OFF32_LIBS
33       _CS_POSIX_V7_ILP32_OFFBIG_CFLAGS
34       _CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS
35       _CS_POSIX_V7_ILP32_OFFBIG_LIBS
36       _CS_POSIX_V7_LP64_OFF64_CFLAGS
37       _CS_POSIX_V7_LP64_OFF64_LDFLAGS
38       _CS_POSIX_V7_LP64_OFF64_LIBS
39       _CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS
40       _CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS
41       _CS_POSIX_V7_LPBIG_OFFBIG_LIBS
42       _CS_POSIX_V7_THREADS_CFLAGS
43       _CS_POSIX_V7_THREADS_LDFLAGS
44       _CS_POSIX_V7_WIDTH_RESTRICTED_ENVS
45       _CS_V7_ENV
46       _CS_POSIX_V6_ILP32_OFF32_CFLAGS
47       _CS_POSIX_V6_ILP32_OFF32_LDFLAGS
48       _CS_POSIX_V6_ILP32_OFF32_LIBS
49       _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS
50       _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS
51       _CS_POSIX_V6_ILP32_OFFBIG_LIBS
52       _CS_POSIX_V6_LP64_OFF64_CFLAGS
53       _CS_POSIX_V6_LP64_OFF64_LDFLAGS
54       _CS_POSIX_V6_LP64_OFF64_LIBS
55       _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS
56       _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS
57       _CS_POSIX_V6_LPBIG_OFFBIG_LIBS
58       _CS_POSIX_V6_WIDTH_RESTRICTED_ENVS
59       _CS_V6_ENV
60
61       If len is not 0, and if name has a configuration-defined  value,  conf‐
62       str() shall copy that value into the len-byte buffer pointed to by buf.
63       If the string to be returned is longer than len  bytes,  including  the
64       terminating  null,  then  confstr()  shall truncate the string to len−1
65       bytes and null-terminate the result. The application  can  detect  that
66       the  string  was truncated by comparing the value returned by confstr()
67       with len.
68
69       If len is 0 and buf is a  null  pointer,  then  confstr()  shall  still
70       return  the  integer  value  as  defined  below, but shall not return a
71       string. If len is 0 but buf is  not  a  null  pointer,  the  result  is
72       unspecified.
73
74       After a call to:
75
76           confstr(_CS_V7_ENV, buf, sizeof(buf))
77
78       the  string  stored  in  buf will contain the <space>-separated list of
79       variable=value environment variable pairs required by  the  implementa‐
80       tion  to create a conforming environment, as described in the implemen‐
81       tations' conformance documentation.
82
83       If the implementation supports  the  POSIX  shell  option,  the  string
84       stored in buf after a call to:
85
86           confstr(_CS_PATH, buf, sizeof(buf))
87
88       can  be  used as a value of the PATH environment variable that accesses
89       all of the standard utilities of POSIX.1‐2008, if the return  value  is
90       less than or equal to sizeof(buf).
91

RETURN VALUE

93       If  name  has a configuration-defined value, confstr() shall return the
94       size of buffer that would be needed to hold the  entire  configuration-
95       defined  value  including the terminating null. If this return value is
96       greater than len, the string returned in buf is truncated.
97
98       If name is invalid, confstr() shall return 0 and set errno to  indicate
99       the error.
100
101       If  name  does  not have a configuration-defined value, confstr() shall
102       return 0 and leave errno unchanged.
103

ERRORS

105       The confstr() function shall fail if:
106
107       EINVAL The value of the name argument is invalid.
108
109       The following sections are informative.
110

EXAMPLES

112       None.
113

APPLICATION USAGE

115       An application can distinguish between an invalid name parameter  value
116       and one that corresponds to a configurable variable that has no config‐
117       uration-defined value by checking if errno is  modified.  This  mirrors
118       the behavior of sysconf().
119
120       The original need for this function was to provide a way of finding the
121       configuration-defined default value for the environment variable  PATH.
122       Since  PATH  can  be  modified  by the user to include directories that
123       could contain utilities replacing the standard utilities in  the  Shell
124       and Utilities volume of POSIX.1‐2008, applications need a way to deter‐
125       mine the system-supplied PATH environment variable value that  contains
126       the correct search path for the standard utilities.
127
128       An application could use:
129
130           confstr(name, (char *)NULL, (size_t)0)
131
132       to  find  out how big a buffer is needed for the string value; use mal‐
133       loc() to allocate a buffer to hold the string; and call confstr() again
134       to  get the string. Alternately, it could allocate a fixed, static buf‐
135       fer that is big enough to  hold  most  answers  (perhaps  512  or  1024
136       bytes),  but  then use malloc() to allocate a larger buffer if it finds
137       that this is too small.
138

RATIONALE

140       Application developers can normally determine any  configuration  vari‐
141       able by means of reading from the stream opened by a call to:
142
143           popen("command -p getconf variable", "r");
144
145       The  confstr()  function  with  a  name  argument of _CS_PATH returns a
146       string that can be used as a PATH  environment  variable  setting  that
147       will  reference  the  standard  shell and utilities as described in the
148       Shell and Utilities volume of POSIX.1‐2008.
149
150       The confstr() function copies the returned string into  a  buffer  sup‐
151       plied  by  the  application instead of returning a pointer to a string.
152       This allows a cleaner function in some implementations (such  as  those
153       with  lightweight threads) and resolves questions about when the appli‐
154       cation must copy the string returned.
155

FUTURE DIRECTIONS

157       None.
158

SEE ALSO

160       exec, fpathconf(), sysconf()
161
162       The Base Definitions volume of POSIX.1‐2008, <unistd.h>
163
164       The Shell and Utilities volume of POSIX.1‐2008, c99
165
167       Portions of this text are reprinted and reproduced in  electronic  form
168       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
169       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
170       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
171       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
172       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
173       event of any discrepancy between this version and the original IEEE and
174       The  Open Group Standard, the original IEEE and The Open Group Standard
175       is the referee document. The original Standard can be  obtained  online
176       at http://www.unix.org/online.html .
177
178       Any  typographical  or  formatting  errors that appear in this page are
179       most likely to have been introduced during the conversion of the source
180       files  to  man page format. To report such errors, see https://www.ker
181       nel.org/doc/man-pages/reporting_bugs.html .
182
183
184
185IEEE/The Open Group                  2013                          CONFSTR(3P)
Impressum