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