usr.bin/getconf/getconf.1

   1 .\"
   2 .\" Copyright 2000 Massachusetts Institute of Technology
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software and
   5 .\" its documentation for any purpose and without fee is hereby
   6 .\" granted, provided that both the above copyright notice and this
   7 .\" permission notice appear in all copies, that both the above
   8 .\" copyright notice and this permission notice appear in all
   9 .\" supporting documentation, and that the name of M.I.T. not be used
  10 .\" in advertising or publicity pertaining to distribution of the
  11 .\" software without specific, written prior permission.  M.I.T. makes
  12 .\" no representations about the suitability of this software for any
  13 .\" purpose.  It is provided "as is" without express or implied
  14 .\" warranty.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
  17 .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  20 .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  23 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  24 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  25 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  26 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd September 15, 2017
  32 .Dt GETCONF 1
  33 .Os
  34 .Sh NAME
  35 .Nm getconf
  36 .Nd retrieve standard configuration variables
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Fl a
  40 .Op Ar file
  41 .Nm
  42 .Op Fl v Ar environment
  43 .Ar path_var
  44 .Ar file
  45 .Nm
  46 .Op Fl v Ar environment
  47 .Ar system_var
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility prints the values of
  52 .Tn POSIX
  53 or
  54 .Tn X/Open
  55 path or system configuration variables to the standard output.
  56 If a variable is undefined, the string
  57 .Dq Li undefined
  58 is output.
  59 .Pp
  60 The first form of the command displays all of the path or system configuration
  61 variables to standard output.
  62 If
  63 .Ar file
  64 is provided,
  65 all path configuration variables are reported for
  66 .Ar file
  67 using
  68 .Xr pathconf 2 .
  69 Otherwise,
  70 all system configuration variables are reported using
  71 .Xr confstr 3
  72 and
  73 .Xr sysconf 3 .
  74 .Pp
  75 The second form of the command, with two mandatory
  76 arguments, retrieves file- and file system-specific
  77 configuration variables using
  78 .Xr pathconf 2 .
  79 The third form, with a single argument, retrieves system
  80 configuration variables using
  81 .Xr confstr 3
  82 and
  83 .Xr sysconf 3 ,
  84 depending on the type of variable.
  85 As an extension, the second form can also be used to query static limits from
  86 .In limits.h .
  87 .Pp
  88 All
  89 .Xr sysconf 3
  90 and
  91 .Xr pathconf 2
  92 variables use the same name as the manifest constants defined in
  93 the relevant standard C-language bindings, including any leading
  94 underscore or prefix.
  95 That is to say,
  96 .Ar system_var
  97 might be
  98 .Dv ARG_MAX
  99 or
 100 .Dv _POSIX_VERSION ,
 101 as opposed to the
 102 .Xr sysconf 3
 103 names
 104 .Dv _SC_ARG_MAX
 105 or
 106 .Dv _SC_POSIX_VERSION .
 107 Variables retrieved from
 108 .Xr confstr 3
 109 have the leading
 110 .Ql _CS_
 111 stripped off; thus,
 112 .Dv _CS_PATH
 113 is queried by a
 114 .Ar system_var
 115 of
 116 .Dq Li PATH .
 117 .Ss Programming Environments
 118 The
 119 .Fl v Ar environment
 120 option specifies a
 121 .St -p1003.1-2001
 122 programming environment under which the values are to be queried.
 123 This option currently does nothing, but may in the future be used
 124 to select between 32-bit and 64-bit execution environments on platforms
 125 which support both.
 126 Specifying an environment which is not supported on the current execution
 127 platform gives undefined results.
 128 .Pp
 129 The standard programming environments are as follows:
 130 .Bl -tag -width ".Li POSIX_V6_LPBIG_OFFBIG" -offset indent
 131 .It Li POSIX_V6_ILP32_OFF32
 132 Exactly 32-bit integer, long, pointer, and file offset.
 133 .Sy Supported platforms :
 134 None.
 135 .It Li POSIX_V6_ILP32_OFFBIG
 136 Exactly 32-bit integer, long, and pointer; at least 64-bit file offset.
 137 .Sy Supported platforms :
 138 .Tn IA32 ,
 139 .Tn PowerPC .
 140 .It Li POSIX_V6_LP64_OFF64
 141 Exactly 32-bit integer; exactly 64-bit long, pointer, and file offset.
 142 .Sy Supported platforms :
 143 .Tn AMD64 ,
 144 .Tn SPARC64 .
 145 .It Li POSIX_V6_LPBIG_OFFBIG
 146 At least 32-bit integer; at least 64-bit long, pointer, and file offset.
 147 .Sy Supported platforms :
 148 None.
 149 .El
 150 .Pp
 151 The command:
 152 .Pp
 153 .Dl "getconf POSIX_V6_WIDTH_RESTRICTED_ENVS"
 154 .Pp
 155 returns a newline-separated list of environments in which the width
 156 of certain fundamental types is no greater than the width of the native
 157 C type
 158 .Vt long .
 159 At present, all programming environments supported by
 160 .Fx
 161 have this property.
 162 Several of the
 163 .Xr confstr 3
 164 variables provide information on the necessary compiler and linker flags
 165 to use the standard programming environments described above.
 166 .Sh EXIT STATUS
 167 .Ex -std
 168 .Sh EXAMPLES
 169 The command:
 170 .Pp
 171 .Dl "getconf PATH"
 172 .Pp
 173 will display the system default setting for the
 174 .Ev PATH
 175 environment variable.
 176 .Pp
 177 The command:
 178 .Pp
 179 .Dl "getconf NAME_MAX /tmp"
 180 .Pp
 181 will display the maximum length of a filename in the
 182 .Pa /tmp
 183 directory.
 184 .Pp
 185 The command:
 186 .Pp
 187 .Dl "getconf -v POSIX_V6_LPBIG_OFFBIG LONG_MAX"
 188 .Pp
 189 will display the maximum value of the C type
 190 .Vt long
 191 in the
 192 .Li POSIX_V6_LPBIG_OFFBIG
 193 programming environment,
 194 if the system supports that environment.
 195 .Sh DIAGNOSTICS
 196 Use of a
 197 .Ar system_var
 198 or
 199 .Ar path_var
 200 which is completely unrecognized is considered an error,
 201 causing a diagnostic message to be written to standard error.
 202 One
 203 which is known but merely undefined does not result in an error
 204 indication.
 205 The
 206 .Nm
 207 utility recognizes all of the variables defined for
 208 .St -p1003.1-2001 ,
 209 including those which are not currently implemented.
 210 .Sh SEE ALSO
 211 .Xr pathconf 2 ,
 212 .Xr confstr 3 ,
 213 .Xr sysconf 3
 214 .Sh STANDARDS
 215 The
 216 .Nm
 217 utility is expected to be compliant with
 218 .St -p1003.1-2001 .
 219 .Sh HISTORY
 220 The
 221 .Nm
 222 utility first appeared in
 223 .Fx 5.0 .
 224 .Sh AUTHORS
 225 .An Garrett A. Wollman Aq Mt wollman@lcs.mit.edu