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