1.\"	$OpenBSD: confstr.3,v 1.20 2014/01/21 03:15:45 schwarze Exp $
2.\"
3.\" Copyright (c) 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.Dd $Mdocdate: January 21 2014 $
31.Dt CONFSTR 3
32.Os
33.Sh NAME
34.Nm confstr
35.Nd get string-valued configurable variables
36.Sh SYNOPSIS
37.In unistd.h
38.Ft size_t
39.Fn confstr "int name" "char *buf" "size_t len"
40.Sh DESCRIPTION
41The
42.Fn confstr
43function provides a method for applications to get configuration
44defined string values.
45.Pp
46The
47.Fa name
48argument specifies the system variable to be queried.
49Symbolic constants for each name value are found in the include file
50.In unistd.h .
51The
52.Fa len
53argument specifies the size of the buffer referenced by the
54argument
55.Fa buf .
56If
57.Fa len
58is non-zero,
59.Fa buf
60is a non-null pointer, and
61.Fa name
62has a value; up to
63.Fa len
64\- 1 bytes of the value are copied into the buffer
65.Fa buf .
66The copied value is always NUL terminated.
67.Pp
68The available values are as follows:
69.Bl -tag -width "123456" -compact
70.It Li _CS_PATH
71Return a value for the
72.Ev PATH
73environment variable that finds all the standard utilities.
74.Pp
75.It Li _CS_V7_ENV
76Return a space separated list of environment variable assignments
77(other than
78.Ev PATH )
79necessary for obtaining a shell environment compliant with
80.St -p1003.1-2008 .
81.Pp
82.It Li _CS_V6_ENV
83Return a space separated list of environment variable assignments
84(other than
85.Ev PATH )
86necessary for obtaining a shell environment compliant with
87.St -p1003.1-2001 .
88.Pp
89.It Li _CS_POSIX_V7_THREADS_CFLAGS
90Return the compiler flags for compiling objects in a program that
91uses multiple threads.
92.Pp
93.It Li _CS_POSIX_V7_THREADS_LDFLAGS
94Return the linker flags for linking an executable that uses multiple
95threads.
96.Pp
97.It Li _CS_POSIX_V7_WIDTH_RESTRICTED_ENVS
98.It Li _CS_POSIX_V6_WIDTH_RESTRICTED_ENVS
99Return a newline separated list of supported compilation environments
100in which none of the following types are wider than type
101.Vt long :
102.Vt blksize_t , cc_t , mode_t , nfds_t , pid_t , ptrdiff_t , size_t ,
103.Vt speed_t , ssize_t , suseconds_t , tcflag_t , wchar_t ,
104and
105.Vt wint_t .
106.Pp
107.It Li _CS_POSIX_V7_ILP32_OFFBIG_CFLAGS
108.It Li _CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS
109.It Li _CS_POSIX_V7_ILP32_OFFBIG_LIBS
110.It Li _CS_POSIX_V6_ILP32_OFFBIG_CFLAGS
111.It Li _CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS
112.It Li _CS_POSIX_V6_ILP32_OFFBIG_LIBS
113If
114.Fn sysconf _SC_V7_ILP32_OFFBIG
115returns a value greater than zero,
116return the compiler flags for compiling objects,
117the linker flags for linking an executable,
118or the linker arguments for additional libraries, respectively,
119for a compilation environment with 32-bit
120.Vt int , long ,
121and
122.Vt pointer
123types and an
124.Vt off_t
125type that has a width of at least 64 bits.
126Otherwise, the result is unspecified.
127.Pp
128.It Li _CS_POSIX_V7_LP64_OFF64_CFLAGS
129.It Li _CS_POSIX_V7_LP64_OFF64_LDFLAGS
130.It Li _CS_POSIX_V7_LP64_OFF64_LIBS
131.It Li _CS_POSIX_V6_LP64_OFF64_CFLAGS
132.It Li _CS_POSIX_V6_LP64_OFF64_LDFLAGS
133.It Li _CS_POSIX_V6_LP64_OFF64_LIBS
134If
135.Fn sysconf _SC_V7_LP64_OFF64
136returns a value greater than zero,
137return the compiler flags for compiling objects,
138the linker flags for linking an executable,
139or the linker arguments for additional libraries, respectively,
140for a compilation environment with 64-bit
141.Vt int , long , pointer ,
142and
143.Vt off_t
144types.
145Otherwise, the result is unspecified.
146.Pp
147.It Li _CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS
148.It Li _CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS
149.It Li _CS_POSIX_V7_LPBIG_OFFBIG_LIBS
150.It Li _CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS
151.It Li _CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS
152.It Li _CS_POSIX_V6_LPBIG_OFFBIG_LIBS
153If
154.Fn sysconf _SC_V7_LPBIG_OFFBIG
155returns a value greater than zero,
156return the compiler flags for compiling objects,
157the linker flags for linking an executable,
158or the linker arguments for additional libraries, respectively,
159for a compilation environment with
160.Vt int , long , pointer ,
161and
162.Vt off_t
163types that all have widths of at least 64 bits.
164Otherwise, the result is unspecified.
165.El
166.Sh RETURN VALUES
167If the call to
168.Nm
169is not successful, 0 is returned and
170.Va errno
171is set appropriately.
172Otherwise, if the variable does not have a configuration defined value,
1730 is returned and
174.Va errno
175is not modified.
176Otherwise, the buffer size needed to hold the entire configuration-defined
177value is returned.
178If this size is greater than the argument
179.Fa len ,
180the string in
181.Fa buf
182was truncated.
183.Sh ERRORS
184The
185.Nm
186function will fail if:
187.Bl -tag -width Er
188.It Bq Er EINVAL
189The value of the
190.Fa name
191argument is invalid.
192.El
193.Sh SEE ALSO
194.Xr pathconf 2 ,
195.Xr sysconf 3
196.Sh STANDARDS
197The
198.Nm
199function conforms to
200.St -p1003.1-2008 .
201.Sh HISTORY
202The
203.Nm
204function first appeared in
205.Bx 4.4 .
206