mirror of https://github.com/mkerrisk/man-pages
460 lines
11 KiB
Groff
460 lines
11 KiB
Groff
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "GETCONF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" getconf
|
||
|
.SH NAME
|
||
|
getconf \- get configuration values
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fBgetconf\fP \fB[\fP \fB-v specification\fP \fB]\fP \fIsystem_var\fP\fB
|
||
|
.br
|
||
|
.sp
|
||
|
getconf\fP \fB[\fP \fB-v specification\fP \fB]\fP \fIpath_var pathname\fP\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
In the first synopsis form, the \fIgetconf\fP utility shall write
|
||
|
to the standard output the value of the variable specified by
|
||
|
the \fIsystem_var\fP operand.
|
||
|
.LP
|
||
|
In the second synopsis form, the \fIgetconf\fP utility shall write
|
||
|
to the standard output the value of the variable specified
|
||
|
by the \fIpath_var\fP operand for the path specified by the \fIpathname\fP
|
||
|
operand.
|
||
|
.LP
|
||
|
The value of each configuration variable shall be determined as if
|
||
|
it were obtained by calling the function from which it is
|
||
|
defined to be available by this volume of IEEE\ Std\ 1003.1-2001 or
|
||
|
by the System Interfaces volume of
|
||
|
IEEE\ Std\ 1003.1-2001 (see the OPERANDS section). The value shall
|
||
|
reflect conditions in the current operating
|
||
|
environment.
|
||
|
.SH OPTIONS
|
||
|
.LP
|
||
|
The \fIgetconf\fP utility shall conform to the Base Definitions volume
|
||
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
||
|
.LP
|
||
|
The following option shall be supported:
|
||
|
.TP 7
|
||
|
\fB-v\ \fP \fIspecification\fP
|
||
|
.sp
|
||
|
Indicate a specific specification and version for which configuration
|
||
|
variables shall be determined. If this option is not
|
||
|
specified, the values returned correspond to an implementation default
|
||
|
conforming compilation environment.
|
||
|
.LP
|
||
|
If the command:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgetconf _POSIX_V6_ILP32_OFF32
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
does not write \fB"-1\\n"\fP or \fB"undefined\\n"\fP to standard output,
|
||
|
then commands of the form:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgetconf -v POSIX_V6_ILP32_OFF32 ...
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
determine values for configuration variables corresponding to the
|
||
|
POSIX_V6_ILP32_OFF32 compilation environment specified in \fIc99\fP
|
||
|
, the EXTENDED DESCRIPTION.
|
||
|
.LP
|
||
|
If the command:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgetconf _POSIX_V6_ILP32_OFFBIG
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
does not write \fB"-1\\n"\fP or \fB"undefined\\n"\fP to standard output,
|
||
|
then commands of the form:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgetconf -v POSIX_V6_ILP32_OFFBIG ...
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
determine values for configuration variables corresponding to the
|
||
|
POSIX_V6_ILP32_OFFBIG compilation environment specified in \fIc99\fP
|
||
|
, the EXTENDED DESCRIPTION.
|
||
|
.LP
|
||
|
If the command:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgetconf _POSIX_V6_LP64_OFF64
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
does not write \fB"-1\\n"\fP or \fB"undefined\\n"\fP to standard output,
|
||
|
then commands of the form:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgetconf -v POSIX_V6_LP64_OFF64 ...
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
determine values for configuration variables corresponding to the
|
||
|
POSIX_V6_LP64_OFF64 compilation environment specified in \fIc99\fP
|
||
|
, the EXTENDED DESCRIPTION.
|
||
|
.LP
|
||
|
If the command:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgetconf _POSIX_V6_LPBIG_OFFBIG
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
does not write \fB"-1\\n"\fP or \fB"undefined\\n"\fP to standard output,
|
||
|
then commands of the form:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgetconf -v POSIX_V6_LPBIG_OFFBIG ...
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
determine values for configuration variables corresponding to the
|
||
|
POSIX_V6_LPBIG_OFFBIG compilation environment specified in \fIc99\fP
|
||
|
, the EXTENDED DESCRIPTION.
|
||
|
.sp
|
||
|
.SH OPERANDS
|
||
|
.LP
|
||
|
The following operands shall be supported:
|
||
|
.TP 7
|
||
|
\fIpath_var\fP
|
||
|
A name of a configuration variable. All of the variables in the Variable
|
||
|
column of the table in the DESCRIPTION of the \fIfpathconf\fP() function
|
||
|
defined in the System Interfaces volume of
|
||
|
IEEE\ Std\ 1003.1-2001, without the enclosing braces, shall be supported.
|
||
|
The implementation may add other local
|
||
|
variables.
|
||
|
.TP 7
|
||
|
\fIpathname\fP
|
||
|
A pathname for which the variable specified by \fIpath_var\fP is to
|
||
|
be determined.
|
||
|
.TP 7
|
||
|
\fIsystem_var\fP
|
||
|
A name of a configuration variable. All of the following variables
|
||
|
shall be supported:
|
||
|
.RS
|
||
|
.IP " *" 3
|
||
|
The names in the Variable column of the table in the DESCRIPTION of
|
||
|
the \fIsysconf\fP()
|
||
|
function in the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
|
||
|
except for the entries corresponding to _SC_CLK_TCK,
|
||
|
_SC_GETGR_R_SIZE_MAX, and _SC_GETPW_R_SIZE_MAX, without the enclosing
|
||
|
braces.
|
||
|
.LP
|
||
|
For compatibility with earlier versions, the following variable names
|
||
|
shall also be supported:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
POSIX2_C_BIND
|
||
|
POSIX2_C_DEV
|
||
|
POSIX2_CHAR_TERM
|
||
|
POSIX2_FORT_DEV
|
||
|
POSIX2_FORT_RUN
|
||
|
POSIX2_LOCALEDEF
|
||
|
POSIX2_SW_DEV
|
||
|
POSIX2_UPE
|
||
|
POSIX2_VERSION
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
and shall be equivalent to the same name prefixed with an underscore.
|
||
|
This requirement may be removed in a future version.
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
The names of the symbolic constants used as the \fIname\fP argument
|
||
|
of the \fIconfstr\fP() function in the System Interfaces volume of
|
||
|
IEEE\ Std\ 1003.1-2001,
|
||
|
without the _CS_ prefix.
|
||
|
.LP
|
||
|
.IP " *" 3
|
||
|
The names of the symbolic constants listed under the headings ``Maximum
|
||
|
Values'' and ``Minimum Values'' in the description of
|
||
|
the \fI<limits.h>\fP header in the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, without the enclosing braces.
|
||
|
.LP
|
||
|
For compatibility with earlier versions, the following variable names
|
||
|
shall also be supported:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
POSIX2_BC_BASE_MAX
|
||
|
POSIX2_BC_DIM_MAX
|
||
|
POSIX2_BC_SCALE_MAX
|
||
|
POSIX2_BC_STRING_MAX
|
||
|
POSIX2_COLL_WEIGHTS_MAX
|
||
|
POSIX2_EXPR_NEST_MAX
|
||
|
POSIX2_LINE_MAX
|
||
|
POSIX2_RE_DUP_MAX
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
and shall be equivalent to the same name prefixed with an underscore.
|
||
|
This requirement may be removed in a future version.
|
||
|
.LP
|
||
|
.RE
|
||
|
.LP
|
||
|
The implementation may add other local values.
|
||
|
.sp
|
||
|
.SH STDIN
|
||
|
.LP
|
||
|
Not used.
|
||
|
.SH INPUT FILES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH ENVIRONMENT VARIABLES
|
||
|
.LP
|
||
|
The following environment variables shall affect the execution of
|
||
|
\fIgetconf\fP:
|
||
|
.TP 7
|
||
|
\fILANG\fP
|
||
|
Provide a default value for the internationalization variables that
|
||
|
are unset or null. (See the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
||
|
for
|
||
|
the precedence of internationalization variables used to determine
|
||
|
the values of locale categories.)
|
||
|
.TP 7
|
||
|
\fILC_ALL\fP
|
||
|
If set to a non-empty string value, override the values of all the
|
||
|
other internationalization variables.
|
||
|
.TP 7
|
||
|
\fILC_CTYPE\fP
|
||
|
Determine the locale for the interpretation of sequences of bytes
|
||
|
of text data as characters (for example, single-byte as
|
||
|
opposed to multi-byte characters in arguments).
|
||
|
.TP 7
|
||
|
\fILC_MESSAGES\fP
|
||
|
Determine the locale that should be used to affect the format and
|
||
|
contents of diagnostic messages written to standard
|
||
|
error.
|
||
|
.TP 7
|
||
|
\fINLSPATH\fP
|
||
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
||
|
\&.\fP
|
||
|
.sp
|
||
|
.SH ASYNCHRONOUS EVENTS
|
||
|
.LP
|
||
|
Default.
|
||
|
.SH STDOUT
|
||
|
.LP
|
||
|
If the specified variable is defined on the system and its value is
|
||
|
described to be available from the \fIconfstr\fP() function defined
|
||
|
in the System Interfaces volume of
|
||
|
IEEE\ Std\ 1003.1-2001, its value shall be written in the following
|
||
|
format:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%s\\n", <\fP\fIvalue\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
Otherwise, if the specified variable is defined on the system, its
|
||
|
value shall be written in the following format:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"%d\\n", <\fP\fIvalue\fP\fB>
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
If the specified variable is valid, but is undefined on the system,
|
||
|
\fIgetconf\fP shall write using the following format:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fB"undefined\\n"
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
If the variable name is invalid or an error occurs, nothing shall
|
||
|
be written to standard output.
|
||
|
.SH STDERR
|
||
|
.LP
|
||
|
The standard error shall be used only for diagnostic messages.
|
||
|
.SH OUTPUT FILES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH EXTENDED DESCRIPTION
|
||
|
.LP
|
||
|
None.
|
||
|
.SH EXIT STATUS
|
||
|
.LP
|
||
|
The following exit values shall be returned:
|
||
|
.TP 7
|
||
|
\ 0
|
||
|
The specified variable is valid and information about its current
|
||
|
state was written successfully.
|
||
|
.TP 7
|
||
|
>0
|
||
|
An error occurred.
|
||
|
.sp
|
||
|
.SH CONSEQUENCES OF ERRORS
|
||
|
.LP
|
||
|
Default.
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
The following example illustrates the value of {NGROUPS_MAX}:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgetconf NGROUPS_MAX
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
The following example illustrates the value of {NAME_MAX} for a specific
|
||
|
directory:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgetconf NAME_MAX /usr
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
The following example shows how to deal more carefully with results
|
||
|
that might be unspecified:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBif value=$(getconf PATH_MAX /usr); then
|
||
|
if [ "$value" = "undefined" ]; then
|
||
|
echo PATH_MAX in /usr is infinite.
|
||
|
else
|
||
|
echo PATH_MAX in /usr is $value.
|
||
|
fi
|
||
|
else
|
||
|
echo Error in getconf.
|
||
|
fi
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
Note that:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBsysconf(_SC_POSIX_C_BIND);
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
and:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBsystem("getconf POSIX2_C_BIND");
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
in a C program could give different answers. The \fIsysconf\fP() call
|
||
|
supplies a value
|
||
|
that corresponds to the conditions when the program was either compiled
|
||
|
or executed, depending on the implementation; the \fIsystem\fP() call
|
||
|
to \fIgetconf\fP always supplies a value corresponding to conditions
|
||
|
when the
|
||
|
program is executed.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
The original need for this utility, and for the \fIconfstr\fP() function,
|
||
|
was to
|
||
|
provide a way of finding the configuration-defined default value for
|
||
|
the \fIPATH\fP environment variable. Since \fIPATH\fP can be
|
||
|
modified by the user to include directories that could contain utilities
|
||
|
replacing the standard utilities, shell scripts need a way
|
||
|
to determine the system-supplied \fIPATH\fP environment variable value
|
||
|
that contains the correct search path for the standard
|
||
|
utilities. It was later suggested that access to the other variables
|
||
|
described in this volume of IEEE\ Std\ 1003.1-2001
|
||
|
could also be useful to applications.
|
||
|
.LP
|
||
|
This functionality of \fIgetconf\fP would not be adequately subsumed
|
||
|
by another command such as:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBgrep\fP \fIvar\fP \fB/etc/conf
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
because such a strategy would provide correct values for neither those
|
||
|
variables that can vary at runtime, nor those that can
|
||
|
vary depending on the path.
|
||
|
.LP
|
||
|
Early proposal versions of \fIgetconf\fP specified exit status 1 when
|
||
|
the specified variable was valid, but not defined on the
|
||
|
system. The output string \fB"undefined"\fP is now used to specify
|
||
|
this case with exit code 0 because so many things depend on
|
||
|
an exit code of zero when an invoked utility is successful.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIc99\fP , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
||
|
\fI<limits.h>\fP, the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
|
||
|
\fIconfstr\fP(), \fIpathconf\fP(), \fIsysconf\fP(), \fIsystem\fP()
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|