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