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: src/usr.bin/getconf/getconf.1,v 1.9.2.2 2003/02/25 20:31:18 trhodes Exp $
  30 .\"
  31 .Dd September 18, 2002
  32 .Dt GETCONF 1
  33 .Os
  34 .Sh NAME
  35 .Nm getconf
  36 .Nd retrieve standard configuration variables
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl v Ar environment
  40 .Ar path_var
  41 .Ar file
  42 .Nm
  43 .Op Fl v Ar environment
  44 .Ar system_var
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility prints the value of a
  49 .Tn POSIX
  50 or
  51 .Tn X/Open
  52 path or system configuration variable to the standard output.
  53 If the specified variable is undefined, the string
  54 .Dq Li undefined
  55 is output.
  56 .Pp
  57 The first form of the command, with two mandatory
  58 arguments, retrieves file- and file system-specific
  59 configuration variables using
  60 .Xr pathconf 2 .
  61 The second form, with a single argument, retrieves system
  62 configuration variables using
  63 .Xr confstr 3
  64 and
  65 .Xr sysconf 3 ,
  66 depending on the type of variable.
  67 As an extension, the second form can also be used to query static limits from
  68 .Aq Pa limits.h .
  69 .Pp
  70 All
  71 .Xr sysconf 3
  72 and
  73 .Xr pathconf 2
  74 variables use the same name as the manifest constants defined in
  75 the relevant standard C-language bindings, including any leading
  76 underscore or prefix.
  77 That is to say,
  78 .Ar system_var
  79 might be
  80 .Dv ARG_MAX
  81 or
  82 .Dv _POSIX_VERSION ,
  83 as opposed to the
  84 .Xr sysconf 3
  85 names
  86 .Dv _SC_ARG_MAX
  87 or
  88 .Dv _SC_POSIX_VERSION .
  89 Variables retrieved from
  90 .Xr confstr 3
  91 have the leading
  92 .Ql _CS_
  93 stripped off; thus,
  94 .Dv _CS_PATH
  95 is queried by a
  96 .Ar system_var
  97 of
  98 .Dq Li PATH .
  99 .Ss Programming Environments
 100 The
 101 .Fl v Ar environment
 102 option specifies a
 103 .St -p1003.1-2001
 104 programming environment under which the values are to be queried.
 105 This option currently does nothing, but may in the future be used
 106 to select between 32-bit and 64-bit execution environments on platforms
 107 which support both.
 108 Specifying an environment which is not supported on the current execution
 109 platform gives undefined results.
 110 .Pp
 111 The standard programming environments are as follows:
 112 .Bl -tag -width ".Li POSIX_V6_LPBIG_OFFBIG" -offset indent
 113 .It Li POSIX_V6_ILP32_OFF32
 114 Exactly 32-bit integer, long, pointer, and file offset.
 115 .Sy Supported platforms :
 116 None.
 117 .It Li POSIX_V6_ILP32_OFFBIG
 118 Exactly 32-bit integer, long, and pointer; at least 64-bit file offset.
 119 .Sy Supported platforms :
 120 .Tn IA32 ,
 121 .Tn PowerPC .
 122 .It Li POSIX_V6_LP64_OFF64
 123 Exactly 32-bit integer; exactly 64-bit long, pointer, and file offset.
 124 .Sy Supported platforms :
 125 .Tn Alpha ,
 126 .Tn SPARC64 .
 127 .It Li POSIX_V6_LPBIG_OFFBIG
 128 At least 32-bit integer; at least 64-bit long, pointer, and file offset.
 129 .Sy Supported platforms :
 130 None.
 131 .El
 132 .Pp
 133 The command:
 134 .Pp
 135 .Dl "getconf POSIX_V6_WIDTH_RESTRICTED_ENVS"
 136 .Pp
 137 returns a newline-separated list of environments in which the width
 138 of certain fundamental types is no greater than the width of the native
 139 C type
 140 .Vt long .
 141 At present, all programming environments supported by
 142 .Fx
 143 have this property.
 144 Several of the
 145 .Xr confstr 3
 146 variables provide information on the necessary compiler and linker flags
 147 to use the standard programming environments described above.
 148 .Sh DIAGNOSTICS
 149 .Ex -std
 150 Use of a
 151 .Ar system_var
 152 or
 153 .Ar path_var
 154 which is completely unrecognized is considered an error,
 155 causing a diagnostic message to be written to standard error.
 156 One
 157 which is known but merely undefined does not result in an error
 158 indication.
 159 The
 160 .Nm
 161 utility recognizes all of the variables defined for
 162 .St -p1003.1-2001 ,
 163 including those which are not currently implemented.
 164 .Sh EXAMPLES
 165 The command:
 166 .Pp
 167 .Dl "getconf PATH"
 168 .Pp
 169 will display the system default setting for the
 170 .Ev PATH
 171 environment variable.
 172 .Pp
 173 The command:
 174 .Pp
 175 .Dl "getconf NAME_MAX /tmp"
 176 .Pp
 177 will display the maximum length of a filename in the
 178 .Pa /tmp
 179 directory.
 180 .Pp
 181 The command:
 182 .Pp
 183 .Dl "getconf -v POSIX_V6_LPBIG_OFFBIG LONG_MAX"
 184 .Pp
 185 will display the maximum value of the C type
 186 .Vt long
 187 in the
 188 .Li POSIX_V6_LPBIG_OFFBIG
 189 programming environment,
 190 if the system supports that environment.
 191 .Sh SEE ALSO
 192 .Xr pathconf 2 ,
 193 .Xr confstr 3 ,
 194 .Xr sysconf 3
 195 .Sh STANDARDS
 196 The
 197 .Nm
 198 utility is expected to be compliant with
 199 .St -p1003.1-2001 .
 200 .Sh HISTORY
 201 The
 202 .Nm
 203 utility first appeared in
 204 .Fx 5.0 .
 205 .Sh AUTHORS
 206 .An Garrett A. Wollman Aq wollman@lcs.mit.edu