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