1 '\" te
   2 .\" Copyright 1989 AT&T
   3 .\" Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
   4 .\" Copyright (c) 2014, Joyent, Inc.  All Rights Reserved
   5 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   6 .\" 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.
   7 .\" 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.
   8 .\" 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]
   9 .TH ENVIRON 5 "Jun 26, 2014"
  10 .SH NAME
  11 environ \- user environment
  12 .SH DESCRIPTION
  13 .LP
  14 When a process begins execution, one of the \fBexec\fR family of functions
  15 makes available an array of strings called the environment; see \fBexec\fR(2).
  16 By convention, these strings have the form \fIvariable=value\fR, for example,
  17 \fBPATH=/sbin:/usr/sbin\fR. These environmental variables provide a way to make
  18 information about a program's environment available to programs.
  19 .LP
  20 A name may be placed in the environment by the \fBexport\fR command and
  21 \fIname\fR=\fIvalue\fR arguments in \fBsh\fR(1), or by one of the \fBexec\fR
  22 functions. It is unwise to conflict with certain shell variables such as
  23 \fBMAIL\fR, \fBPS1\fR, \fBPS2\fR, and \fBIFS\fR that are frequently exported by
  24 \fB\&.profile\fR files; see \fBprofile\fR(4).
  25 .LP
  26 The following environmental variables can be used by applications and are
  27 expected to be set in the target run-time environment.
  28 .sp
  29 .ne 2
  30 .na
  31 \fB\fBHOME\fR\fR
  32 .ad
  33 .sp .6
  34 .RS 4n
  35 The name of the user's login directory, set by \fBlogin\fR(1) from the password
  36 file; see \fBpasswd\fR(4).
  37 .RE
  38 
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fBLANG\fR\fR
  43 .ad
  44 .sp .6
  45 .RS 4n
  46 The string used to specify internationalization information that allows users
  47 to work with different national conventions. The \fBsetlocale\fR(3C) and
  48 \fBnewlocale\fR(3C) functions
  49 check the \fBLANG\fR environment variable when they are called with \fB""\fR as
  50 the \fBlocale\fR argument.  \fBLANG\fR is used as the default locale if the
  51 corresponding environment variable for a particular category is unset or null.
  52 If, however,  \fBLC_ALL\fR is set to a valid, non-empty value, its contents are
  53 used to override both the \fBLANG\fR and the other \fBLC_*\fR variables. For
  54 example, when invoked as \fBsetlocale(LC_CTYPE, "")\fR, \fBsetlocale()\fR will
  55 query the \fBLC_CTYPE\fR environment variable first to see if it is set and
  56 non-null. If \fBLC_CTYPE\fR is not set or null, then \fBsetlocale()\fR will
  57 check the \fBLANG\fR environment variable to see if it is set and non-null. If
  58 both \fBLANG\fR and \fBLC_CTYPE\fR are unset or \fINULL\fR, the default "C"
  59 locale will be used to set the \fBLC_CTYPE\fR category.
  60 .sp
  61 Most commands will invoke \fBsetlocale(LC_ALL, "")\fR prior to any other
  62 processing. This allows the command to be used with different national
  63 conventions by setting the appropriate environment variables. In addition, some
  64 commands will use
  65 .BR uselocale (3C)
  66 to set a thread-specific locale.
  67 .sp
  68 The following environment variables correspond to each category of
  69 \fBsetlocale\fR(3C):
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fBLC_ALL\fR\fR
  74 .ad
  75 .sp .6
  76 .RS 4n
  77 If set to a valid, non-empty string value, override the values of \fBLANG\fR
  78 and all the other \fBLC_*\fRvariables.
  79 .RE
  80 
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBLC_COLLATE\fR\fR
  85 .ad
  86 .sp .6
  87 .RS 4n
  88 This category specifies the character collation sequence being used.  The
  89 information corresponding to this category is stored in a database  created by
  90 the \fBlocaledef\fR(1) command.  This environment variable affects
  91 \fBstrcoll\fR(3C) and \fBstrxfrm\fR(3C).
  92 .RE
  93 
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBLC_CTYPE\fR\fR
  98 .ad
  99 .sp .6
 100 .RS 4n
 101 This category specifies character classification, character conversion, and
 102 widths of multibyte characters. When \fBLC_CTYPE\fR is set to a valid value,
 103 the calling utility can display and handle text and file names containing valid
 104 characters for that locale;   Extended Unix Code (EUC) characters where any
 105 individual character can be 1, 2, or 3 bytes wide; and EUC characters of 1, 2,
 106 or 3 column widths. The default "C" locale corresponds to the 7-bit \fBASCII\fR
 107 character set; only characters from ISO 8859-1 are valid. The information
 108 corresponding to this category is stored in a database created by the
 109 \fBlocaledef()\fR command.  This environment variable is used by
 110 \fBctype\fR(3C), \fBmblen\fR(3C), and many commands, such as \fBcat\fR(1),
 111 \fBed\fR(1), \fBls\fR(1), and \fBvi\fR(1).
 112 .RE
 113 
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBLC_MESSAGES\fR\fR
 118 .ad
 119 .sp .6
 120 .RS 4n
 121 This category specifies the language of the message database being used. For
 122 example, an application may have one message database with French messages, and
 123 another database with German messages. Message databases are created by the
 124 \fBmkmsgs\fR(1) command. This environment variable is used by \fBexstr\fR(1),
 125 \fBgettxt\fR(1), \fBsrchtxt\fR(1), \fBgettxt\fR(3C), and \fBgettext\fR(3C).
 126 .RE
 127 
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBLC_MONETARY\fR\fR
 132 .ad
 133 .sp .6
 134 .RS 4n
 135 This category specifies the monetary symbols and delimiters used for a
 136 particular locale.  The information corresponding to this category is stored in
 137 a database created by the \fBlocaledef\fR(1) command. This environment variable
 138 is used by \fBlocaleconv\fR(3C).
 139 .RE
 140 
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fBLC_NUMERIC\fR\fR
 145 .ad
 146 .sp .6
 147 .RS 4n
 148 This category specifies the decimal and thousands delimiters. The information
 149 corresponding to this category is stored in a database  created by the
 150 \fBlocaledef()\fR command. The default \fBC\fR locale corresponds to \fB"."\fR
 151 as the decimal delimiter and no thousands delimiter. This environment variable
 152 is used by \fBlocaleconv\fR(3C), \fBprintf\fR(3C), and \fBstrtod\fR(3C).
 153 .RE
 154 
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBLC_TIME\fR\fR
 159 .ad
 160 .sp .6
 161 .RS 4n
 162 This category specifies date and time formats. The information corresponding to
 163 this category is stored in a database specified in \fBlocaledef()\fR. The
 164 default \fBC\fR locale corresponds to U.S. date and time formats. This
 165 environment variable is used by many commands and functions; for example:
 166 \fBat\fR(1), \fBcalendar\fR(1), \fBdate\fR(1), \fBstrftime\fR(3C), and
 167 \fBgetdate\fR(3C).
 168 .RE
 169 
 170 .RE
 171 
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fBMSGVERB\fR\fR
 176 .ad
 177 .sp .6
 178 .RS 4n
 179 Controls which standard format message components \fBfmtmsg\fR selects when
 180 messages are displayed to \fBstderr\fR; see  \fBfmtmsg\fR(1) and
 181 \fBfmtmsg\fR(3C).
 182 .RE
 183 
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBNETPATH\fR\fR
 188 .ad
 189 .sp .6
 190 .RS 4n
 191 A colon-separated list of network identifiers. A network identifier is a
 192 character string used by the Network Selection component of the system to
 193 provide application-specific default network search paths. A network identifier
 194 must consist of non-null characters and must have a length of at least 1. No
 195 maximum length is specified. Network identifiers are normally chosen by the
 196 system administrator. A network identifier is also the first field in any
 197 \fB/etc/netconfig\fR file entry. \fBNETPATH\fR thus provides a link into the
 198 \fB/etc/netconfig\fR file and the information about a network contained in that
 199 network's entry. \fB/etc/netconfig\fR is maintained by the system
 200 administrator. The library routines described in \fBgetnetpath\fR(3NSL) access
 201 the \fBNETPATH\fR environment variable.
 202 .RE
 203 
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBNLSPATH\fR\fR
 208 .ad
 209 .sp .6
 210 .RS 4n
 211 Contains a sequence of templates which \fBcatopen\fR(3C) and \fBgettext\fR(3C)
 212 use when attempting to locate message catalogs. Each template consists of an
 213 optional prefix, one or more substitution fields, a filename and an optional
 214 suffix. For example:
 215 .sp
 216 .in +2
 217 .nf
 218 NLSPATH="/system/nlslib/%N.cat"
 219 .fi
 220 .in -2
 221 .sp
 222 
 223 defines that \fBcatopen()\fR should look for all message catalogs in the
 224 directory \fB/system/nlslib\fR, where the catalog name should be constructed
 225 from the \fIname\fR parameter passed to \fBcatopen\fR(\|), \fB%N\fR, with the
 226 suffix \fB\&.cat\fR.
 227 .sp
 228 Substitution fields consist of a \fB%\fR symbol, followed by a single-letter
 229 keyword. The following keywords are currently defined:
 230 .sp
 231 .ne 2
 232 .na
 233 \fB%N\fR
 234 .ad
 235 .sp .6
 236 .RS 4n
 237 The value of the \fIname\fR parameter passed to \fBcatopen()\fR.
 238 .RE
 239 
 240 .sp
 241 .ne 2
 242 .na
 243 \fB%L\fR
 244 .ad
 245 .sp .6
 246 .RS 4n
 247 The value of \fBLANG\fR or \fBLC_MESSAGES\fR.
 248 .RE
 249 
 250 .sp
 251 .ne 2
 252 .na
 253 \fB%l\fR
 254 .ad
 255 .sp .6
 256 .RS 4n
 257 The language element from \fBLANG\fR or \fBLC_MESSAGES\fR.
 258 .RE
 259 
 260 .sp
 261 .ne 2
 262 .na
 263 \fB%t\fR
 264 .ad
 265 .sp .6
 266 .RS 4n
 267 The territory element from \fBLANG\fR or \fBLC_MESSAGES\fR.
 268 .RE
 269 
 270 .sp
 271 .ne 2
 272 .na
 273 \fB%c\fR
 274 .ad
 275 .sp .6
 276 .RS 4n
 277 The codeset element from \fBLANG\fR or \fBLC_MESSAGES\fR.
 278 .RE
 279 
 280 .sp
 281 .ne 2
 282 .na
 283 \fB%%\fR
 284 .ad
 285 .sp .6
 286 .RS 4n
 287 A single \fB%\fR character.
 288 .RE
 289 
 290 An empty string is substituted if the specified value is not currently defined.
 291 The separators "\fB_\fR" and "\fB\&.\fR" are not included in \fB%t\fR and
 292 \fB%c\fR substitutions.
 293 .sp
 294 Templates defined in \fBNLSPATH\fR are separated by colons (\fB:\fR). A leading
 295 colon or two adjacent colons (\fB::\fR) is equivalent to specifying \fB%N\fR.
 296 For example:
 297 .sp
 298 .in +2
 299 .nf
 300 NLSPATH=":%N.cat:/nlslib/%L/%N.cat"
 301 .fi
 302 .in -2
 303 .sp
 304 
 305 indicates to \fBcatopen()\fR that it should look for the requested message
 306 catalog in \fIname\fR, \fIname\fR\fB\&.cat\fR and
 307 \fB/nlslib/$LANG/\fR\fIname\fR.cat. For \fBgettext()\fR, \fB%N\fR automatically
 308 maps to "messages".
 309 .sp
 310 If \fBNLSPATH\fR is unset or \fINULL\fR, \fBcatopen()\fR and \fBgettext()\fR
 311 call  \fBsetlocale\fR(3C), which checks \fBLANG\fR and the  \fBLC_*\fR
 312 variables to locate the message catalogs.
 313 .sp
 314 \fBNLSPATH\fR will normally be set up on a system wide basis (in
 315 \fB/etc/profile\fR) and thus makes the location and naming conventions
 316 associated with message catalogs transparent to both programs and users.
 317 .RE
 318 
 319 .sp
 320 .ne 2
 321 .na
 322 \fB\fBPATH\fR\fR
 323 .ad
 324 .sp .6
 325 .RS 4n
 326 The sequence of directory prefixes that \fBsh\fR(1), \fBtime\fR(1),
 327 \fBnice\fR(1), \fBnohup\fR(1), and other utilities apply in searching for a
 328 file known by an incomplete path name. The prefixes are separated by colons
 329 (\fB:\fR). \fBlogin\fR(1) sets \fBPATH=/usr/bin\fR. For more detail, see
 330 \fBsh\fR(1).
 331 .RE
 332 
 333 .sp
 334 .ne 2
 335 .na
 336 \fB\fBSEV_LEVEL\fR\fR
 337 .ad
 338 .sp .6
 339 .RS 4n
 340 Define severity levels and associate and print strings with them in standard
 341 format error messages; see  \fBaddseverity\fR(3C), \fBfmtmsg\fR(1), and
 342 \fBfmtmsg\fR(3C).
 343 .RE
 344 
 345 .sp
 346 .ne 2
 347 .na
 348 \fB\fBTERM\fR\fR
 349 .ad
 350 .sp .6
 351 .RS 4n
 352 The kind of terminal for which output is to be prepared. This information is
 353 used by commands, such as \fBvi\fR(1), which may exploit special capabilities
 354 of that terminal.
 355 .RE
 356 
 357 .sp
 358 .ne 2
 359 .na
 360 \fB\fBTZ\fR\fR
 361 .ad
 362 .sp .6
 363 .RS 4n
 364 Timezone information. The contents of this environment variable are used by the
 365 functions \fBctime\fR(3C), \fBlocaltime\fR(3C), \fBstrftime\fR(3C), and
 366 \fBmktime\fR(3C) to override the default timezone. The value of \fBTZ\fR has
 367 one of the two formats (spaces inserted for clarity):
 368 .sp
 369 .in +2
 370 .nf
 371 :characters
 372 .fi
 373 .in -2
 374 
 375 or
 376 .sp
 377 .in +2
 378 .nf
 379 std offset dst offset, rule
 380 .fi
 381 .in -2
 382 
 383 If \fBTZ\fR is of the first format (that is, if the first character is a colon
 384 (:)), or if \fBTZ\fR is not of the second format, then \fBTZ\fR designates a
 385 path to a timezone database file relative to \fB/usr/share/lib/zoneinfo/\fR,
 386 ignoring a leading colon if one exists.
 387 .sp
 388 Otherwise, \fBTZ\fR is of the second form, which when expanded is as follows:
 389 .sp
 390 .in +2
 391 .nf
 392 \fIstdoffset\fR[\fIdst\fR[\fIoffset\fR][,\fIstart\fR[/\fItime\fR],\fIend\fR[/\fItime\fR]]]
 393 .fi
 394 .in -2
 395 
 396 .sp
 397 .ne 2
 398 .na
 399 \fB\fIstd\fR and \fIdst\fR\fR
 400 .ad
 401 .sp .6
 402 .RS 4n
 403 Indicate no less than three, nor more than {\fBTZNAME_MAX\fR}, bytes that are
 404 the designation for the standard (\fIstd\fR) or the alternative (\fIdst\fR,
 405 such as Daylight Savings Time) timezone. Only \fIstd\fR is required; if
 406 \fIdst\fR is missing, then the alternative time does not apply in this
 407 timezone. Each of these fields can occur in either of two formats, quoted or
 408 unquoted:
 409 .RS +4
 410 .TP
 411 .ie t \(bu
 412 .el o
 413 In the quoted form, the first character is the less-than ('<') character and
 414 the last character is the greater-than ('>') character. All characters between
 415 these quoting characters are alphanumeric characters from the portable
 416 character set in the current locale, the plus-sign ('+') character, or the
 417 minus-sign ('-') character. The \fIstd\fR and \fIdst\fR fields in this case do
 418 not include the quoting characters.
 419 .RE
 420 .RS +4
 421 .TP
 422 .ie t \(bu
 423 .el o
 424 In the unquoted form, all characters in these fields are alphabetic characters
 425 from the portable character set in the current locale.
 426 .RE
 427 The interpretation of these fields is unspecified if either field is less than
 428 three bytes (except for the case when \fIdst\fR is missing), more than
 429 {\fBTZNAME_MAX\fR} bytes, or if they contain characters other than those
 430 specified.
 431 .RE
 432 
 433 .sp
 434 .ne 2
 435 .na
 436 \fB\fIoffset\fR\fR
 437 .ad
 438 .sp .6
 439 .RS 4n
 440 Indicate the value one must add to the local time to arrive at Coordinated
 441 Universal Time. The offset has the form:
 442 .sp
 443 .in +2
 444 .nf
 445 \fIhh\fR[:\fImm\fR[:\fIss\fR]]
 446 .fi
 447 .in -2
 448 .sp
 449 
 450 The minutes (\fImm\fR) and seconds (\fIss\fR) are optional. The hour (\fIhh\fR)
 451 is required and can be a single digit. The \fIoffset\fR following \fIstd\fR is
 452 required. If no \fIoffset\fR follows \fIdst\fR, daylight savings time is
 453 assumed to be one hour ahead of standard time. One or more digits can be used.
 454 The value is always interpreted as a decimal number. The hour must be between 0
 455 and 24, and the minutes (and seconds), if present, must be between 0 and 59.
 456 Out of range values can cause unpredictable behavior. If preceded by a "-", the
 457 timezone is east of the Prime Meridian. Otherwise, it is west of the Prime
 458 Meridian (which can be indicated by an optional preceding "\fI+\fR" sign).
 459 .RE
 460 
 461 .sp
 462 .ne 2
 463 .na
 464 \fB\fIstart\fR/\fItime\fR,\|\fIend\fR/\fItime\fR\fR
 465 .ad
 466 .sp .6
 467 .RS 4n
 468 Indicate when to change to and back from daylight savings time, where
 469 \fIstart/time\fR describes when the change from standard time to daylight
 470 savings time occurs, and \fIend/time\fR describes when the change back occurs.
 471 Each \fItime\fR field describes when, in current local time, the change is
 472 made.
 473 .sp
 474 The formats of \fIstart\fR and \fIend\fR are one of the following:
 475 .sp
 476 .ne 2
 477 .na
 478 \fB\fBJ\fR\fIn\fR\fR
 479 .ad
 480 .sp .6
 481 .RS 4n
 482 The Julian day \fIn\fR (1 \(<= \fIn\fR \(<= 365). Leap days are not counted.
 483 That is, in all years, February 28 is day 59 and March 1 is day 60. It is
 484 impossible to refer to the occasional February 29.
 485 .RE
 486 
 487 .sp
 488 .ne 2
 489 .na
 490 \fB\fIn\fR\fR
 491 .ad
 492 .sp .6
 493 .RS 4n
 494 The zero-based Julian day (0 \(<= \fIn\fR \(<= 365). Leap days are counted, and
 495 it is possible to refer to February 29.
 496 .RE
 497 
 498 .sp
 499 .ne 2
 500 .na
 501 \fB\fBM\fR\fIm.n.d\fR\fR
 502 .ad
 503 .sp .6
 504 .RS 4n
 505 The \fId\fR^th day, (0 \(<= \fId\fR \(<= 6) of week \fIn\fR of month \fIm\fR of
 506 the year (1 \(<= \fIn\fR \(<= 5, 1 \(<= \fIm\fR \(<= 12), where week 5 means
 507 "the last \fId\fR-day in month \fIm\fR" which may occur in either the fourth or
 508 the fifth week). Week 1 is the first week in which the \fId\fR^th day occurs.
 509 Day zero is Sunday.
 510 .RE
 511 
 512 Implementation specific defaults are used for \fIstart\fR and \fIend\fR if
 513 these optional fields are not specified.
 514 .sp
 515 The \fItime\fR has the same format as \fIoffset\fR except that no leading sign
 516 ("-" or "+" ) is allowed. If \fItime\fR is not specified, the default value is
 517 02:00:00.
 518 .RE
 519 
 520 .RE
 521 
 522 .SH SEE ALSO
 523 .LP
 524 \fBcat\fR(1), \fBdate\fR(1), \fBed\fR(1), \fBfmtmsg\fR(1), \fBlocaledef\fR(1),
 525 \fBlogin\fR(1), \fBls\fR(1), \fBmkmsgs\fR(1), \fBnice\fR(1), \fBnohup\fR(1),
 526 \fBsh\fR(1), \fBsort\fR(1), \fBtime\fR(1), \fBvi\fR(1), \fBexec\fR(2),
 527 \fBaddseverity\fR(3C), \fBcatopen\fR(3C), \fBctime\fR(3C), \fBctype\fR(3C),
 528 \fBfmtmsg\fR(3C), \fBgetdate\fR(3C), \fBgetnetpath\fR(3NSL), \fBgettext\fR(3C),
 529 \fBgettxt\fR(3C), \fBlocaleconv\fR(3C), \fBmblen\fR(3C), \fBmktime\fR(3C),
 530 \fBnewlocale\fR(3C),
 531 \fBprintf\fR(3C), \fBsetlocale\fR(3C), \fBstrcoll\fR(3C), \fBstrftime\fR(3C),
 532 \fBstrtod\fR(3C), \fBstrxfrm\fR(3C), \fBuselocale\fR(3C), \fBTIMEZONE\fR(4),
 533 \fBnetconfig\fR(4), \fBpasswd\fR(4), \fBprofile\fR(4)