path: root/usr/src/man/man5/environ.5

'\" te
.\" Copyright 1989 AT&T
.\" Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
.\" Copyright (c) 2014, Joyent, Inc.  All Rights Reserved
.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH ENVIRON 5 "Jun 26, 2014"
.SH NAME
environ \- user environment
.SH DESCRIPTION
.LP
When a process begins execution, one of the \fBexec\fR family of functions
makes available an array of strings called the environment; see \fBexec\fR(2).
By convention, these strings have the form \fIvariable=value\fR, for example,
\fBPATH=/sbin:/usr/sbin\fR. These environmental variables provide a way to make
information about a program's environment available to programs.
.LP
A name may be placed in the environment by the \fBexport\fR command and
\fIname\fR=\fIvalue\fR arguments in \fBsh\fR(1), or by one of the \fBexec\fR
functions. It is unwise to conflict with certain shell variables such as
\fBMAIL\fR, \fBPS1\fR, \fBPS2\fR, and \fBIFS\fR that are frequently exported by
\fB\&.profile\fR files; see \fBprofile\fR(4).
.LP
The following environmental variables can be used by applications and are
expected to be set in the target run-time environment.
.sp
.ne 2
.na
\fB\fBHOME\fR\fR
.ad
.sp .6
.RS 4n
The name of the user's login directory, set by \fBlogin\fR(1) from the password
file; see \fBpasswd\fR(4).
.RE

.sp
.ne 2
.na
\fB\fBLANG\fR\fR
.ad
.sp .6
.RS 4n
The string used to specify internationalization information that allows users
to work with different national conventions. The \fBsetlocale\fR(3C) and
\fBnewlocale\fR(3C) functions
check the \fBLANG\fR environment variable when they are called with \fB""\fR as
the \fBlocale\fR argument.  \fBLANG\fR is used as the default locale if the
corresponding environment variable for a particular category is unset or null.
If, however,  \fBLC_ALL\fR is set to a valid, non-empty value, its contents are
used to override both the \fBLANG\fR and the other \fBLC_*\fR variables. For
example, when invoked as \fBsetlocale(LC_CTYPE, "")\fR, \fBsetlocale()\fR will
query the \fBLC_CTYPE\fR environment variable first to see if it is set and
non-null. If \fBLC_CTYPE\fR is not set or null, then \fBsetlocale()\fR will
check the \fBLANG\fR environment variable to see if it is set and non-null. If
both \fBLANG\fR and \fBLC_CTYPE\fR are unset or \fINULL\fR, the default "C"
locale will be used to set the \fBLC_CTYPE\fR category.
.sp
Most commands will invoke \fBsetlocale(LC_ALL, "")\fR prior to any other
processing. This allows the command to be used with different national
conventions by setting the appropriate environment variables. In addition, some
commands will use
.BR uselocale (3C)
to set a thread-specific locale.
.sp
The following environment variables correspond to each category of
\fBsetlocale\fR(3C):
.sp
.ne 2
.na
\fB\fBLC_ALL\fR\fR
.ad
.sp .6
.RS 4n
If set to a valid, non-empty string value, override the values of \fBLANG\fR
and all the other \fBLC_*\fRvariables.
.RE

.sp
.ne 2
.na
\fB\fBLC_COLLATE\fR\fR
.ad
.sp .6
.RS 4n
This category specifies the character collation sequence being used.  The
information corresponding to this category is stored in a database  created by
the \fBlocaledef\fR(1) command.  This environment variable affects
\fBstrcoll\fR(3C) and \fBstrxfrm\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBLC_CTYPE\fR\fR
.ad
.sp .6
.RS 4n
This category specifies character classification, character conversion, and
widths of multibyte characters. When \fBLC_CTYPE\fR is set to a valid value,
the calling utility can display and handle text and file names containing valid
characters for that locale;   Extended Unix Code (EUC) characters where any
individual character can be 1, 2, or 3 bytes wide; and EUC characters of 1, 2,
or 3 column widths. The default "C" locale corresponds to the 7-bit \fBASCII\fR
character set; only characters from ISO 8859-1 are valid. The information
corresponding to this category is stored in a database created by the
\fBlocaledef()\fR command.  This environment variable is used by
\fBctype\fR(3C), \fBmblen\fR(3C), and many commands, such as \fBcat\fR(1),
\fBed\fR(1), \fBls\fR(1), and \fBvi\fR(1).
.RE

.sp
.ne 2
.na
\fB\fBLC_MESSAGES\fR\fR
.ad
.sp .6
.RS 4n
This category specifies the language of the message database being used. For
example, an application may have one message database with French messages, and
another database with German messages. Message databases are created by the
\fBmkmsgs\fR(1) command. This environment variable is used by \fBexstr\fR(1),
\fBgettxt\fR(1), \fBsrchtxt\fR(1), \fBgettxt\fR(3C), and \fBgettext\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBLC_MONETARY\fR\fR
.ad
.sp .6
.RS 4n
This category specifies the monetary symbols and delimiters used for a
particular locale.  The information corresponding to this category is stored in
a database created by the \fBlocaledef\fR(1) command. This environment variable
is used by \fBlocaleconv\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBLC_NUMERIC\fR\fR
.ad
.sp .6
.RS 4n
This category specifies the decimal and thousands delimiters. The information
corresponding to this category is stored in a database  created by the
\fBlocaledef()\fR command. The default \fBC\fR locale corresponds to \fB"."\fR
as the decimal delimiter and no thousands delimiter. This environment variable
is used by \fBlocaleconv\fR(3C), \fBprintf\fR(3C), and \fBstrtod\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBLC_TIME\fR\fR
.ad
.sp .6
.RS 4n
This category specifies date and time formats. The information corresponding to
this category is stored in a database specified in \fBlocaledef()\fR. The
default \fBC\fR locale corresponds to U.S. date and time formats. This
environment variable is used by many commands and functions; for example:
\fBat\fR(1), \fBcalendar\fR(1), \fBdate\fR(1), \fBstrftime\fR(3C), and
\fBgetdate\fR(3C).
.RE

.RE

.sp
.ne 2
.na
\fB\fBMSGVERB\fR\fR
.ad
.sp .6
.RS 4n
Controls which standard format message components \fBfmtmsg\fR selects when
messages are displayed to \fBstderr\fR; see  \fBfmtmsg\fR(1) and
\fBfmtmsg\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBNETPATH\fR\fR
.ad
.sp .6
.RS 4n
A colon-separated list of network identifiers. A network identifier is a
character string used by the Network Selection component of the system to
provide application-specific default network search paths. A network identifier
must consist of non-null characters and must have a length of at least 1. No
maximum length is specified. Network identifiers are normally chosen by the
system administrator. A network identifier is also the first field in any
\fB/etc/netconfig\fR file entry. \fBNETPATH\fR thus provides a link into the
\fB/etc/netconfig\fR file and the information about a network contained in that
network's entry. \fB/etc/netconfig\fR is maintained by the system
administrator. The library routines described in \fBgetnetpath\fR(3NSL) access
the \fBNETPATH\fR environment variable.
.RE

.sp
.ne 2
.na
\fB\fBNLSPATH\fR\fR
.ad
.sp .6
.RS 4n
Contains a sequence of templates which \fBcatopen\fR(3C) and \fBgettext\fR(3C)
use when attempting to locate message catalogs. Each template consists of an
optional prefix, one or more substitution fields, a filename and an optional
suffix. For example:
.sp
.in +2
.nf
NLSPATH="/system/nlslib/%N.cat"
.fi
.in -2
.sp

defines that \fBcatopen()\fR should look for all message catalogs in the
directory \fB/system/nlslib\fR, where the catalog name should be constructed
from the \fIname\fR parameter passed to \fBcatopen\fR(\|), \fB%N\fR, with the
suffix \fB\&.cat\fR.
.sp
Substitution fields consist of a \fB%\fR symbol, followed by a single-letter
keyword. The following keywords are currently defined:
.sp
.ne 2
.na
\fB%N\fR
.ad
.sp .6
.RS 4n
The value of the \fIname\fR parameter passed to \fBcatopen()\fR.
.RE

.sp
.ne 2
.na
\fB%L\fR
.ad
.sp .6
.RS 4n
The value of \fBLANG\fR or \fBLC_MESSAGES\fR.
.RE

.sp
.ne 2
.na
\fB%l\fR
.ad
.sp .6
.RS 4n
The language element from \fBLANG\fR or \fBLC_MESSAGES\fR.
.RE

.sp
.ne 2
.na
\fB%t\fR
.ad
.sp .6
.RS 4n
The territory element from \fBLANG\fR or \fBLC_MESSAGES\fR.
.RE

.sp
.ne 2
.na
\fB%c\fR
.ad
.sp .6
.RS 4n
The codeset element from \fBLANG\fR or \fBLC_MESSAGES\fR.
.RE

.sp
.ne 2
.na
\fB%%\fR
.ad
.sp .6
.RS 4n
A single \fB%\fR character.
.RE

An empty string is substituted if the specified value is not currently defined.
The separators "\fB_\fR" and "\fB\&.\fR" are not included in \fB%t\fR and
\fB%c\fR substitutions.
.sp
Templates defined in \fBNLSPATH\fR are separated by colons (\fB:\fR). A leading
colon or two adjacent colons (\fB::\fR) is equivalent to specifying \fB%N\fR.
For example:
.sp
.in +2
.nf
NLSPATH=":%N.cat:/nlslib/%L/%N.cat"
.fi
.in -2
.sp

indicates to \fBcatopen()\fR that it should look for the requested message
catalog in \fIname\fR, \fIname\fR\fB\&.cat\fR and
\fB/nlslib/$LANG/\fR\fIname\fR.cat. For \fBgettext()\fR, \fB%N\fR automatically
maps to "messages".
.sp
If \fBNLSPATH\fR is unset or \fINULL\fR, \fBcatopen()\fR and \fBgettext()\fR
call  \fBsetlocale\fR(3C), which checks \fBLANG\fR and the  \fBLC_*\fR
variables to locate the message catalogs.
.sp
\fBNLSPATH\fR will normally be set up on a system wide basis (in
\fB/etc/profile\fR) and thus makes the location and naming conventions
associated with message catalogs transparent to both programs and users.
.RE

.sp
.ne 2
.na
\fB\fBPATH\fR\fR
.ad
.sp .6
.RS 4n
The sequence of directory prefixes that \fBsh\fR(1), \fBtime\fR(1),
\fBnice\fR(1), \fBnohup\fR(1), and other utilities apply in searching for a
file known by an incomplete path name. The prefixes are separated by colons
(\fB:\fR). \fBlogin\fR(1) sets \fBPATH=/usr/bin\fR. For more detail, see
\fBsh\fR(1).
.RE

.sp
.ne 2
.na
\fB\fBSEV_LEVEL\fR\fR
.ad
.sp .6
.RS 4n
Define severity levels and associate and print strings with them in standard
format error messages; see  \fBaddseverity\fR(3C), \fBfmtmsg\fR(1), and
\fBfmtmsg\fR(3C).
.RE

.sp
.ne 2
.na
\fB\fBTERM\fR\fR
.ad
.sp .6
.RS 4n
The kind of terminal for which output is to be prepared. This information is
used by commands, such as \fBvi\fR(1), which may exploit special capabilities
of that terminal.
.RE

.sp
.ne 2
.na
\fB\fBTZ\fR\fR
.ad
.sp .6
.RS 4n
Timezone information. The contents of this environment variable are used by the
functions \fBctime\fR(3C), \fBlocaltime\fR(3C), \fBstrftime\fR(3C), and
\fBmktime\fR(3C) to override the default timezone. The value of \fBTZ\fR has
one of the two formats (spaces inserted for clarity):
.sp
.in +2
.nf
:characters
.fi
.in -2

or
.sp
.in +2
.nf
std offset dst offset, rule
.fi
.in -2

If \fBTZ\fR is of the first format (that is, if the first character is a colon
(:)), or if \fBTZ\fR is not of the second format, then \fBTZ\fR designates a
path to a timezone database file relative to \fB/usr/share/lib/zoneinfo/\fR,
ignoring a leading colon if one exists.
.sp
Otherwise, \fBTZ\fR is of the second form, which when expanded is as follows:
.sp
.in +2
.nf
\fIstdoffset\fR[\fIdst\fR[\fIoffset\fR][,\fIstart\fR[/\fItime\fR],\fIend\fR[/\fItime\fR]]]
.fi
.in -2

.sp
.ne 2
.na
\fB\fIstd\fR and \fIdst\fR\fR
.ad
.sp .6
.RS 4n
Indicate no less than three, nor more than {\fBTZNAME_MAX\fR}, bytes that are
the designation for the standard (\fIstd\fR) or the alternative (\fIdst\fR,
such as Daylight Savings Time) timezone. Only \fIstd\fR is required; if
\fIdst\fR is missing, then the alternative time does not apply in this
timezone. Each of these fields can occur in either of two formats, quoted or
unquoted:
.RS +4
.TP
.ie t \(bu
.el o
In the quoted form, the first character is the less-than ('<') character and
the last character is the greater-than ('>') character. All characters between
these quoting characters are alphanumeric characters from the portable
character set in the current locale, the plus-sign ('+') character, or the
minus-sign ('-') character. The \fIstd\fR and \fIdst\fR fields in this case do
not include the quoting characters.
.RE
.RS +4
.TP
.ie t \(bu
.el o
In the unquoted form, all characters in these fields are alphabetic characters
from the portable character set in the current locale.
.RE
The interpretation of these fields is unspecified if either field is less than
three bytes (except for the case when \fIdst\fR is missing), more than
{\fBTZNAME_MAX\fR} bytes, or if they contain characters other than those
specified.
.RE

.sp
.ne 2
.na
\fB\fIoffset\fR\fR
.ad
.sp .6
.RS 4n
Indicate the value one must add to the local time to arrive at Coordinated
Universal Time. The offset has the form:
.sp
.in +2
.nf
\fIhh\fR[:\fImm\fR[:\fIss\fR]]
.fi
.in -2
.sp

The minutes (\fImm\fR) and seconds (\fIss\fR) are optional. The hour (\fIhh\fR)
is required and can be a single digit. The \fIoffset\fR following \fIstd\fR is
required. If no \fIoffset\fR follows \fIdst\fR, daylight savings time is
assumed to be one hour ahead of standard time. One or more digits can be used.
The value is always interpreted as a decimal number. The hour must be between 0
and 24, and the minutes (and seconds), if present, must be between 0 and 59.
Out of range values can cause unpredictable behavior. If preceded by a "-", the
timezone is east of the Prime Meridian. Otherwise, it is west of the Prime
Meridian (which can be indicated by an optional preceding "\fI+\fR" sign).
.RE

.sp
.ne 2
.na
\fB\fIstart\fR/\fItime\fR,\|\fIend\fR/\fItime\fR\fR
.ad
.sp .6
.RS 4n
Indicate when to change to and back from daylight savings time, where
\fIstart/time\fR describes when the change from standard time to daylight
savings time occurs, and \fIend/time\fR describes when the change back occurs.
Each \fItime\fR field describes when, in current local time, the change is
made.
.sp
The formats of \fIstart\fR and \fIend\fR are one of the following:
.sp
.ne 2
.na
\fB\fBJ\fR\fIn\fR\fR
.ad
.sp .6
.RS 4n
The Julian day \fIn\fR (1 \(<= \fIn\fR \(<= 365). Leap days are not counted.
That is, in all years, February 28 is day 59 and March 1 is day 60. It is
impossible to refer to the occasional February 29.
.RE

.sp
.ne 2
.na
\fB\fIn\fR\fR
.ad
.sp .6
.RS 4n
The zero-based Julian day (0 \(<= \fIn\fR \(<= 365). Leap days are counted, and
it is possible to refer to February 29.
.RE

.sp
.ne 2
.na
\fB\fBM\fR\fIm.n.d\fR\fR
.ad
.sp .6
.RS 4n
The \fId\fR^th day, (0 \(<= \fId\fR \(<= 6) of week \fIn\fR of month \fIm\fR of
the year (1 \(<= \fIn\fR \(<= 5, 1 \(<= \fIm\fR \(<= 12), where week 5 means
"the last \fId\fR-day in month \fIm\fR" which may occur in either the fourth or
the fifth week). Week 1 is the first week in which the \fId\fR^th day occurs.
Day zero is Sunday.
.RE

Implementation specific defaults are used for \fIstart\fR and \fIend\fR if
these optional fields are not specified.
.sp
The \fItime\fR has the same format as \fIoffset\fR except that no leading sign
("-" or "+" ) is allowed. If \fItime\fR is not specified, the default value is
02:00:00.
.RE

.RE

.SH SEE ALSO
.LP
\fBcat\fR(1), \fBdate\fR(1), \fBed\fR(1), \fBfmtmsg\fR(1), \fBlocaledef\fR(1),
\fBlogin\fR(1), \fBls\fR(1), \fBmkmsgs\fR(1), \fBnice\fR(1), \fBnohup\fR(1),
\fBsh\fR(1), \fBsort\fR(1), \fBtime\fR(1), \fBvi\fR(1), \fBexec\fR(2),
\fBaddseverity\fR(3C), \fBcatopen\fR(3C), \fBctime\fR(3C), \fBctype\fR(3C),
\fBfmtmsg\fR(3C), \fBgetdate\fR(3C), \fBgetnetpath\fR(3NSL), \fBgettext\fR(3C),
\fBgettxt\fR(3C), \fBlocaleconv\fR(3C), \fBmblen\fR(3C), \fBmktime\fR(3C),
\fBnewlocale\fR(3C),
\fBprintf\fR(3C), \fBsetlocale\fR(3C), \fBstrcoll\fR(3C), \fBstrftime\fR(3C),
\fBstrtod\fR(3C), \fBstrxfrm\fR(3C), \fBuselocale\fR(3C), \fBTIMEZONE\fR(4),
\fBnetconfig\fR(4), \fBpasswd\fR(4), \fBprofile\fR(4)