Environment Variables

 Environment Variable Definition

Environment variables defined in this chapter affect the operation of multiple utilities, functions and applications. There are other environment variables that are of interest only to specific utilities. Environment variables that apply to a single utility only are defined as part of the utility description. See the ENVIRONMENT VARIABLES section of the utility descriptions in the XCU specification for information on environment variable usage.

The value of an environment variable is a string of characters. For a C-language program, an array of strings called the environment is made available when a process begins. The array is pointed to by the external variable environ, which is defined as:

extern char **environ;

These strings have the form name=value; names do not contain the character =. For values to be portable across XSI-conformant systems, the value must be composed of characters from the portable character set (except NUL and as indicated below). There is no meaning associated with the order of strings in the environment. If more than one string in a process' environment has the same name the consequences are undefined.

Environment variable names used by the utilities in the XCU specification consist solely of upper-case letters, digits and the "_" (underscore) from the characters defined in Portable Character Set . Other characters may be permitted by an implementation; applications must tolerate the presence of such names. Upper- and lower-case letters retain their unique identities and are not folded together. The name space of environment variable names containing lower-case letters is reserved for applications. Applications can define any environment variables with names from this name space without modifying the behaviour of the standard utilities.

The values that the environment variables may be assigned are not restricted except that they are considered to end with a null byte and the total space used to store the environment and the arguments to the process is limited to {ARG_MAX} bytes.

Other pairs may be placed in the environment by, for example, calling the putenv() function, manipulating the environ variable, or by using envp arguments when creating a process; see in the XSH specification.

It is unwise to conflict with certain variables that are frequently exported by widely used command interpreters and applications:

ARFLAGS
IFS
MAILPATH
PS1
CC
LANG
MAILRC
PS2
CDPATH
LC_ALL
MAKEFLAGS
PS3
CFLAGS
LC_COLLATE
MAKESHELL
PS4
CHARSET
LC_CTYPE
MANPATH
PWD
COLUMNS
LC_MESSAGES
MBOX
RANDOM
DATEMSK
LC_MONETARY
MORE
SECONDS
DEAD
LC_NUMERIC
MSGVERB
SHELL
EDITOR
LC_TIME
NLSPATH
TERM
ENV
LDFLAGS
NPROC
TERMCAP
EXINIT
LEX
OLDPWD
TERMINFO
FC
LFLAGS
OPTARG
TMPDIR
FCEDIT
LINENO
OPTERR
TZ
FFLAGS
LINES
OPTIND
USER
GET
LISTER
PAGER
VISUAL
GFLAGS
LOGNAME
PATH
YACC
HISTFILE
LPDEST
PPID
YFLAGS
HISTORY
MAIL
PRINTER
 
HISTSIZE
MAILCHECK
PROCLANG
 
HOME
MAILER
PROJECTDIR
 

If the variables in the following two sections are present in the environment during the execution of an application or utility, they are given the meaning described below. Some are placed into the environment by the implementation at the time the user logs in; all can be added or changed by the user or any ancestor of the current process. The implementation will add or change environment variables named in this specification set only as specified in this specification set. If they are defined in the application's environment, the utilities in the XCU specification and the functions in the XSH specification assume they have the specified meaning. Conforming applications must not set these environment variables to have meanings other than as described. See getenv() and the XCU specification, Shell Execution Environment  for methods of accessing these variables.

 Internationalisation Variables

This section describes environment variables that are relevant to the operation of internationalised interfaces described in the CAE Specification, System Interfaces and Headers, Issue 5 and the CAE Specification, Commands and Utilities, Issue 5.

Users may use the following environment variables to announce specific localisation requirements to applications. Applications must retrieve this information using the setlocale() function to initialise the correct behaviour of the internationalised interfaces. The descriptions of the internationalisation environment variables describe the resulting behaviour only when the application locale is initialised in this way.

LANG

This variable determines the locale category for native language, local customs and coded character set in the absence of the LC_ALL and other LC_* (LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME) environment variables. This can be used by applications to determine the language to use for error messages and instructions, collating sequences, date formats, and so forth.

LC_ALL

This variable determines the values for all locale categories. The value of the LC_ALL environment variable has precedence over any of the other environment variables starting with LC_ (LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME) and the LANG environment variable.

LC_COLLATE

This variable determines the locale category for character collation. It determines collation information for regular expressions and sorting, including equivalence classes and multi-character collating elements, in various utilities and the strcoll() and strxfrm() functions. Additional semantics of this variable, if any, are implementation-dependent.

LC_CTYPE

This variable determines the locale category for character handling functions, such as tolower(), toupper() and isalpha(). This environment variable determines the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters), the classification of characters (for example, alpha, digit, graph) and the behaviour of character classes. Additional semantics of this variable, if any, are implementation-dependent.

LC_MESSAGES

This variable determines the locale category for processing affirmative and negative responses and the language and cultural conventions in which messages should be written. It also affects the behaviour of the catopen() function in determining the message catalogue. Additional semantics of this variable, if any, are implementation-dependent. The language and cultural conventions of diagnostic and informative messages whose format is unspecified by this specification set should be affected by the setting of LC_MESSAGES.

LC_MONETARY

This variable determines the locale category for monetary-related numeric formatting information. Additional semantics of this variable, if any, are implementation-dependent.

LC_NUMERIC

This variable determines the locale category for numeric formatting (for example, thousands separator and radix character) information in various utilities as well as the formatted I/O operations in printf() and scanf() and the string conversion functions in strtod(). Additional semantics of this variable, if any, are implementation-dependent.

LC_TIME

This variable determines the locale category for date and time formatting information. It affects the behaviour of the time functions in strftime(). Additional semantics of this variable, if any, are implementation-dependent.

NLSPATH

This variable contains a sequence of templates that the catopen() function uses when attempting to locate message catalogues. Each template consists of an optional prefix, one or more substitution fields, a filename and an optional suffix. For example:

NLSPATH="/system/nlslib/%N.cat"

defines that catopen() should look for all message catalogues in the directory /system/nlslib, where the catalogue name should be constructed from the name parameter passed to catopen() (%N), with the suffix .cat. Substitution fields consist of a "%" symbol, followed by a single-letter keyword. The following keywords are currently defined:

%N

The value of the name parameter passed to catopen().

%L

The value of the LC_MESSAGES category.

%l

The language element from the LC_MESSAGES category.

%t

The territory element from the LC_MESSAGES category.

%c

The codeset element from the LC_MESSAGES category.

%%

A single % character.

An empty string is substituted if the specified value is not currently defined. The separators underscore (_) and period (.) are not included in %t and %c substitutions.

Templates defined in NLSPATH are separated by colons (:). A leading or two adjacent colons :: is equivalent to specifying %N. For example:

NLSPATH=":%N.cat:/nlslib/%L/%N.cat"

indicates to catopen() that it should look for the requested message catalogue in name, name.cat and /nlslib/category/name.cat, where category is the value of the LC_MESSAGES category of the current locale.

Users should not set the NLSPATH variable unless they have a specific reason to override the default system path. Setting NLSPATH to override the default system path produces undefined results in the standard utilities and in applications with appropriate privileges.

The environment variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME, (LC_*), and NLSPATH provide for the support of internationalised applications. The standard utilities make use of these environment variables as described in this section and the individual ENVIRONMENT VARIABLES sections for the utilities. If these variables specify locale categories that are not based upon the same underlying codeset, the results are unspecified.

The values of locale categories are determined by a precedence order; the first condition met below determines the value:

1. If the LC_ALL environment variable is defined and is not null, the value of LC_ALL is used.

2. If the LC_* environment variable ( LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC, LC_TIME) is defined and is not null, the value of the environment variable is used to initialise the category that corresponds to the environment variable.

3. If the LANG environment variable is defined and is not null, the value of the LANG environment variable is used.

4. If the LANG environment variable is not set or is set to the empty string, the implementation-dependent default locale is used.

If the locale value is "C" or "POSIX", the POSIX locale is used and the standard utilities behave in accordance with the rules in POSIX Locale , for the associated category.

If the locale value begins with a slash, it is interpreted as the pathname of a file that was created in the output format used by the localedef utility; see OUTPUT FILES under localedef. Referencing such a pathname will result in that locale being used for the indicated category.

If the locale value has the form:

language[_territory][.codeset]

it refers to an implementation-provided locale, where settings of language, territory and codeset are implementation-dependent.

LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, LC_NUMERIC and LC_TIME are defined to accept an additional field "@modifier ", which allows the user to select a specific instance of localisation data within a single category (for example, for selecting the dictionary as opposed to the character ordering of data). The syntax for these environment variables is thus defined as:

[language[_territory][.codeset][@modifier]]

For example, if a user wanted to interact with the system in French, but required to sort German text files, LANG and LC_COLLATE could be defined as:

LANG=Fr_FR
LC_COLLATE=De_DE

This could be extended to select dictionary collation (say) by use of the @modifier field; for example:

LC_COLLATE=De_DE@dict

An implementation may support other formats.

If the locale value is not recognised by the implementation, the behaviour is unspecified.

At run time, these values are bound to a program's locale by calling the setlocale() function.

Additional criteria for determining a valid locale name are implementation-dependent.

 Other Environment Variables

COLUMNS

A decimal integer > 0 used to indicate the user's preferred width in column positions for the terminal screen or window. (See column position .) If this variable is unset or null, the implementation determines the number of columns, appropriate for the terminal or window, in an unspecified manner. When COLUMNS is set, any terminal-width information implied by TERM will be overridden. Users and portable applications should not set COLUMNS unless they wish to override the system selection and produce output unrelated to the terminal characteristics. The default value for the number of column positions is unspecified because historical implementations use different methods to determine values corresponding to the size of the screen in which the utility is run. This size is typically known to the implementation through the value of TERM or by more elaborate methods such as extensions to the stty utility, or knowledge of how the user is dynamically resizing windows on a bit-mapped display terminal. Users should not need to set this variable in the environment unless there is a specific reason to override the implementation's default behaviour, such as to display data in an area arbitrarily smaller than the terminal or window.

DATEMSK

Indicates the pathname of the template file used by getdate().

HOME

The system will initialise this variable at the time of login to be a pathname of the user's home directory. See <pwd.h>.

LINES

A decimal integer > 0 used to indicate the user's preferred number of lines on a page or the vertical screen or window size in lines. A line in this case is a vertical measure large enough to hold the tallest character in the character set being displayed. If this variable is unset or null, the implementation determines the number of lines, appropriate for the terminal or window (size, terminal baud rate, and so forth), in an unspecified manner. When LINES is set, any terminal-height information implied by TERM will be overridden. Users and portable applications should not set LINES unless they wish to override the system selection and produce output unrelated to the terminal characteristics. The default value for the number of lines is unspecified because historical implementations use different methods to determine values corresponding to the size of the screen in which the utility is run. This size is typically known to the implementation through the value of TERM or by more elaborate methods such as extensions to the stty utility, or knowledge of how the user is dynamically resizing windows on a bit-mapped display terminal. Users should not need to set this variable in the environment unless there is a specific reason to override the implementation's default behaviour, such as to display data in an area arbitrarily smaller than the terminal or window.

LOGNAME

The system will initialise this variable at the time of login to be the user's login name. See <pwd.h>. For a value of LOGNAME to be portable across implementations of the ISO POSIX-1 standard, the value should be composed of characters from the portable filename character set.

MSGVERB

Describes which message components are to be used in writing messages by fmtmsg().

PATH

The sequence of path prefixes that certain functions and utilities apply in searching for an executable file known only by a filename. The prefixes are separated by a colon (:) When a non-zero-length prefix is applied to this filename, a slash is inserted between the prefix and the filename. A zero-length prefix is a legacy feature that indicates the current working directory. It appears as two adjacent colons (::), as an initial colon preceding the rest of the list, or as a trailing colon following the rest of the list. A portable application must use an actual pathname (such as .) to represent the current working directory in PATH. The list is searched from beginning to end, applying the filename to each prefix, until an executable file with the specified name and appropriate execution permissions is found. If the pathname being sought contains a slash, the search through the path prefixes will not be performed. If the pathname begins with a slash, the specified path is resolved (see pathname resolution ). If PATH is unset or is set to null, the path search is implementation-dependent.

SHELL

A pathname of the user's preferred command language interpreter. If this interpreter does not conform to the XSI Shell Command Language in the XCU specification, Shell Command Language , utilities may behave differently from those described in this specification set.

TMPDIR

A pathname of a directory made available for programs that need a place to create temporary files.

TERM

The terminal type for which output is to be prepared. This information is used by utilities and application programs wishing to exploit special capabilities specific to a terminal. The format and allowable values of this environment variable are unspecified.

TZ

Timezone information. The contents of the environment variable named TZ are used by the ctime(), localtime(), strftime() and mktime() functions, and by various utilities, to override the default timezone. The value of TZ has one of the two forms (spaces inserted for clarity):

:characters

or:

std offset dst offset, rule

If TZ is of the first format (that is, if the first character is a colon), the characters following the colon are handled in an implementation-dependent manner. The expanded format (for all TZs whose value does not have a colon as the first character) is as follows:

stdoffset[dst[offset][,start[/time],end[/time]]]

Where:

std and dst

Indicates no less than three, nor more than {TZNAME_MAX}, bytes that are the designation for the standard ( std ) or the alternative ( dst - such as Daylight Savings Time) timezone. Only std is required; if dst is missing, then the alternative time does not apply in this locale. Upper- and lower-case letters are explicitly allowed. Any graphic characters except a leading colon (:) or digits, the comma (,), the minus (-), the plus (+), and the null character are permitted to appear in these fields, but their meaning is unspecified.

offset

Indicates the value one must add to the local time to arrive at Coordinated Universal Time. The offset has the form:

 

hh[:mm[:ss]]

The minutes (mm) and seconds (ss) are optional. The hour (hh) is required and may be a single digit. The offset following std is required. If no offset follows dst, the alternative time is assumed to be one hour ahead of standard time. One or more digits may be used; the value is always interpreted as a decimal number. The hour is between zero and 24, and the minutes (and seconds) if present between zero and 59. Use of values outside these ranges causes undefined behaviour. If preceded by a -, the timezone is east of the Prime Meridian; otherwise it is west (which may be indicated by an optional preceding +).

rule

Indicates when to change to and back from the alternative time. The rule has the form:

date[/time],date[/time]

where the first date describes when the change from standard to alternative time occurs and the second date describes when the change back happens. Each time field describes when, in current local time, the change to the other time is made.

The format of date is one of the following:

Jn

The Julian day n (1 n 365). Leap days are not counted. That is, in all years including leap years February 28 is day 59 and March 1 is day 60. It is impossible to refer explicitly to the occasional February 29.

n

The zero-based Julian day (0 n 365). Leap days are counted, and it is possible to refer to February 29.

Mm.n.d

The d^th day (0 d 6) of week n of month m of the year (1 n 5, 1 m 12, where week 5 means "the last d day in month m" which may occur in either the fourth or the fifth week). Week 1 is the first week in which the day occurs. Day zero is Sunday.

The time has the same format as offset except that no leading sign (- or +) is allowed. The default, if time is not given, is 02:00:00.