IEEE P1003.2 Draft 11.2 - September 1991 Copyright (c) 1991 by the Institute of Electrical and Electronics Engineers, Inc. 345 East 47th Street New York, NY 10017, USA All rights reserved as an unpublished work. This is an unapproved and unpublished IEEE Standards Draft, subject to change. The publication, distribution, or copying of this draft, as well as all derivative works based on this draft, is expressly prohibited except as set forth below. Permission is hereby granted for IEEE Standards Committee participants to reproduce this document for purposes of IEEE standardization activities only, and subject to the restrictions contained herein. Permission is hereby also granted for member bodies and technical committees of ISO and IEC to reproduce this document for purposes of developing a national position, subject to the restrictions contained herein. Permission is hereby also granted to the preceding entities to make limited copies of this document in an electronic form only for the stated activities. The following restrictions apply to reproducing or transmitting the document in any form: 1) all copies or portions thereof must identify the document's IEEE project number and draft number, and must be accompanied by this entire notice in a prominent location; 2) no portion of this document may be redistributed in any modified or abridged form without the prior approval of the IEEE Standards Department. Other entities seeking permission to reproduce this document, or any portion thereof, for standardization or other activities, must contact the IEEE Standards Department for the appropriate license. Use of information contained in this unapproved draft is at your own risk. IEEE Standards Department Copyright and Permissions 445 Hoes Lane, P.O. Box 1331 Piscataway, NJ 08855-1331, USA +1 (908) 562-3800 +1 (908) 562-1571 [FAX] Part 2: SHELL AND UTILITIES P1003.2/D11.2 9 SIGKILL 14 SIGALRM 15 SIGTERM The effects of specifying any _s_i_g_n_a_l__n_u_m_b_e_r other than those listed in the table are undefined. In the obsolescent versions, if the first argument is a negative integer, it shall be interpreted as a -_s_i_g_n_a_l__n_u_m_b_e_r option, not as a negative _p_i_d operand specifying a process group. 4.32.4 Operands The following operands shall be supported by the implementation: _p_i_d A decimal integer specifying a process or process group to be signaled. The process(es) selected by positive, negative, and zero values of the _p_i_d operand shall be as described for POSIX.1 {8} _k_i_l_l() function. If the first _p_i_d operand is negative, it should be preceded by -- to keep it from being interpreted as an option. _e_x_i_t__s_t_a_t_u_s A decimal integer specifying a signal number or the exit status of a process terminated by a signal. 4.32.5 External Influences 4.32.5.1 Standard Input None. 4.32.5.2 Input Files None. 4.32.5.3 Environment Variables The following environment variables shall affect the execution of kill: LANG This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_) do not specify a locale. See 2.6. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.32 kill - Terminate or signal processes 561 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_. LC_CTYPE This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments). LC_MESSAGES This variable shall determine the language in which messages should be written. 4.32.5.4 Asynchronous Events Default. 4.32.6 External Effects 4.32.6.1 Standard Output When the -l option is not specified, the standard output shall not be used. When the -l option is specified, the symbolic name of each signal shall be written in the following format: "%s%c", <_s_i_g_n_a_l__n_a_m_e>, <_s_e_p_a_r_a_t_o_r> where the <_s_i_g_n_a_l__n_a_m_e> is in uppercase, without the SIG prefix, and the <_s_e_p_a_r_a_t_o_r> shall be either a or a . For the last signal written, <_s_e_p_a_r_a_t_o_r> shall be a . When both the -l option and _e_x_i_t__s_t_a_t_u_s operand are specified, the symbolic name of the corresponding signal shall be written in the following format: "%s\n", <_s_i_g_n_a_l__n_a_m_e> 4.32.6.2 Standard Error Used only for diagnostic messages. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 562 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 4.32.6.3 Output Files None. 4.32.7 Extended Description None. 4.32.8 Exit Status The kill utility shall exit with one of the following values: 0 At least one matching process was found for each _p_i_d operand, and the specified signal was successfully processed for at least one matching process. >0 An error occurred. 4.32.9 Consequences of Errors Default. BEGIN_RATIONALE 4.32.10 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) _E_x_a_m_p_l_e_s_,__U_s_a_g_e Any of the commands kill -9 100 -165 kill -s kill 100 -165 kill -s KILL 100 -165 sends the SIGKILL signal to the process whose process ID is 100 and to all processes whose process group ID is 165, assuming the sending process has permission to send that signal to the specified processes, and that they exist. POSIX.1 {8} and POSIX.2 do not require specific signal numbers for any _s_i_g_n_a_l__n_a_m_e_s. Even the -_s_i_g_n_a_l__n_u_m_b_e_r option provides symbolic (although numeric) names for signals. If a process is terminated by a signal, its exit status indicates the signal that killed it, but the exact values are not specified. The kill -l option, however, can be used to map decimal signal numbers and exit status values into the name of a signal. The Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.32 kill - Terminate or signal processes 563 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX following example reports the status of a terminated job: job stat=$? if [ $stat -eq 0 ] then echo job completed successfully. elif [ $stat -gt 128 ] then echo job terminated by signal SIG$(kill -l $stat). else echo job terminated with error code $stat. fi _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The signal name extension was based on a desire to avoid limiting the kill utility to implementation-dependent values. The -l option originated from the C-shell, and is also implemented in the KornShell. The C-shell output can consist of multiple output lines, because the signal names do not always fit on a single line on some terminal screens. The KornShell output also included the implementation-specific signal numbers, and was felt by the working group to be too difficult for scripts to parse conveniently. The specified output format is intended not only to accommodate the historical C-shell output, but also to permit an entirely vertical or entirely horizontal listing on systems for which this is appropriate. An earlier draft invented the name SIGNULL as a _s_i_g_n_a_l__n_a_m_e for signal 0 (used by POSIX.1 {8} to test for the existence of a process without sending it a signal). Since the _s_i_g_n_a_l__n_a_m_e "0" can be used in this case unambiguously, SIGNULL has been removed. An earlier draft also required symbolic _s_i_g_n_a_l__n_a_m_es to be recognized with or without the SIG prefix. Historical versions of kill have not written the SIG prefix for the -l option and have not recognized the SIG prefix on _s_i_g_n_a_l__n_a_m_es. Since neither application portability nor ease of use would be improved by requiring this extension, it is no longer required. POSIX.2 contains no utility that browses for process IDs. Values for _p_i_d are available via the ! and $ parameters of the shell command language (see 3.5.2). The use of numeric signal values was the subject of a long debate in the Working Group. During balloting, it was determined that their use should be declared obsolescent, but retained to provide backward compatibility to existing applications. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 564 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 Existing implementations of kill permit negative _p_i_d operands representing process groups, but this was often unclearly documented. The assumption that an initial negative number argument specifies a signal number (rather than a process group) is the existing behavior, and was retained. Therefore, to send the default signal to a process group (say 123), an application should use a command similar to one of the following: kill -TERM -123 kill -- -123 The -s option was added in response to international interest in providing some form of kill that meets the Utility Syntax Guidelines. Some implementations provide kill only as a shell built-in utility and use that status to support the extension of killing background asynchronous lists (those started with &), by the use of job identifiers. For example, kill %1 would kill the first asynchronous list in the background. This standard does not require (but permits) such an extension, because other related job-control features are not provided by the shell, and because these facilities are not ordinarily usable in portable shell applications. This notation is expected to be introduced by the UPE. END_RATIONALE Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.32 kill - Terminate or signal processes 565 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX 4.33 ln - Link files 4.33.1 Synopsis ln [-f] _s_o_u_r_c_e__f_i_l_e _t_a_r_g_e_t__f_i_l_e ln [-f] _s_o_u_r_c_e__f_i_l_e ... _t_a_r_g_e_t__d_i_r 4.33.2 Description In the first synopsis form, the ln utility shall create a new directory entry (link) for the file specified by the _s_o_u_r_c_e__f_i_l_e operand, at the _d_e_s_t_i_n_a_t_i_o_n path specified by the _t_a_r_g_e_t__f_i_l_e operand. This first synopsis form shall be assumed when the final operand does not name an existing directory; if more than two operands are specified and the final 1 is not an existing directory, an error shall result. 1 In the second synopsis form, the ln utility shall create a new directory entry for each file specified by a _s_o_u_r_c_e__f_i_l_e operand, at a _d_e_s_t_i_n_a_t_i_o_n path in the existing directory named by _t_a_r_g_e_t__d_i_r. If the last operand specifies an existing file of a type not specified by POSIX.1 {8}, the behavior is implementation defined. The corresponding destination path for each _s_o_u_r_c_e__f_i_l_e shall be the concatenation of the target directory pathname, a slash character, and the last pathname component of the _s_o_u_r_c_e__f_i_l_e. The second synopsis form shall be assumed when the final operand names an existing directory. For each _s_o_u_r_c_e__f_i_l_e: (1) If the _d_e_s_t_i_n_a_t_i_o_n path exists: (a) If the -f option is not specified, ln shall write a diagnostic message to standard error, do nothing more with the current _s_o_u_r_c_e__f_i_l_e, and go on to any remaining _s_o_u_r_c_e__f_i_l_e_s. (b) Actions shall be performed equivalent to the POSIX.1 {8} _u_n_l_i_n_k() function, called using _d_e_s_t_i_n_a_t_i_o_n as the _p_a_t_h argument. If this fails for any reason, ln shall write a diagnostic message to standard error, do nothing more with the current _s_o_u_r_c_e__f_i_l_e, and go on to any remaining _s_o_u_r_c_e__f_i_l_e_s. (2) Actions shall be performed equivalent to the POSIX.1 {8} _l_i_n_k() function using _s_o_u_r_c_e__f_i_l_e as the _p_a_t_h_1 argument, and the Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 566 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 _d_e_s_t_i_n_a_t_i_o_n path as the _p_a_t_h_2 argument. 4.33.3 Options The ln utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following option shall be supported by the implementation: -f Force existing _d_e_s_t_i_n_a_t_i_o_n pathnames to be removed to allow the link. 4.33.4 Operands The following operands shall be supported by the implementation: _s_o_u_r_c_e__f_i_l_e A pathname of a file to be linked. This can be a regular or special file; whether a directory can be linked is implementation defined. _t_a_r_g_e_t__f_i_l_e The pathname of the new directory entry to be created. _t_a_r_g_e_t__d_i_r A pathname of an existing directory in which the new directory entries are to be created. 4.33.5 External Influences 4.33.5.1 Standard Input None. 4.33.5.2 Input Files None. 4.33.5.3 Environment Variables The following environment variables shall affect the execution of ln: LANG This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_) do not specify a locale. See 2.6. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.33 ln - Link files 567 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_. LC_CTYPE This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments). LC_MESSAGES This variable shall determine the language in which messages should be written. 4.33.5.4 Asynchronous Events Default. 4.33.6 External Effects 4.33.6.1 Standard Output None. 4.33.6.2 Standard Error Used only for diagnostic messages. 4.33.6.3 Output Files None. 4.33.7 Extended Description None. 4.33.8 Exit Status The ln utility shall exit with one of the following values: 0 All the specified files were linked successfully. >0 An error occurred. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 568 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 4.33.9 Consequences of Errors Default. BEGIN_RATIONALE 4.33.10 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) _E_x_a_m_p_l_e_s_,__U_s_a_g_e None. _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e Some historic versions of ln (including the one specified by the _S_V_I_D) unlink the destination file, if it exists, by default. If the mode does not permit writing, these versions will prompt for confirmation before attempting the unlink. In these versions the -f option causes ln to not attempt to prompt for confirmation. This allows ln to succeed in creating links when the target file already exists, even if the file itself is not writable (although the directory must be). Previous versions of this draft specified this functionality. This draft does not allow the ln utility to unlink existing destination paths by default for the following reasons: - The ln utility has traditionally been used to provide locking for shell applications, a usage that is incompatible with ln unlinking the destination path by default. There was no corresponding technical advantage to adding this functionality. - This functionality gave ln the ability to destroy the link structure of files, which changes the historical behavior of ln. - This functionality is easily replicated with a combination of rm and ln. - It is not historical practice in many systems; BSD and BSD-derived systems do not support this behavior. Unfortunately, whichever behavior is selected can cause scripts written expecting the other behavior to fail. - It is preferable that ln perform in the same manner as the _l_i_n_k() function, which does not permit the target to already exist. This standard retains the -f option to provide support for shell scripts depending on the _S_V_I_D semantics. It seems likely that shell scripts Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.33 ln - Link files 569 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX would not be written to handle prompting by ln, and would therefore have specified the -f option. It should also be noted that -f is an undocumented feature of many historical versions of the ln utility, allowing linking to directories. These versions will require modification. Previous drafts of this standard also required an -i option, which behaved like the -i options in cp and mv, prompting for confirmation before unlinking existing files. This was not historical practice for the ln utility and has been deleted from this version. Although symbolic links are not part of the standard, the -s option should be used only for the traditional purpose of creating symbolic links. END_RATIONALE 4.34 locale - Get locale-specific information 4.34.1 Synopsis locale [ -a | -m ] locale [-ck] _n_a_m_e ... 4.34.2 Description The locale utility shall write information about the current locale environment, or all public locales, to the standard output. For the purposes of this clause, a _p_u_b_l_i_c _l_o_c_a_l_e is one provided by the implementation that is accessible to the application. When locale is invoked without any arguments, it shall summarize the current locale environment for each locale category as determined by the settings of the environment variables defined in 2.5. When invoked with operands, it shall write values that have been assigned to the keywords in the locale categories, as follows: - Specifying a keyword name shall select the named keyword and the category containing that keyword. - Specifying a category name shall select the named category and all keywords in that category. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 570 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 4.34.3 Options The locale utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following options shall be supported by the implementation: -a Write information about all available public locales. The available locales shall include POSIX, representing the POSIX Locale. The manner in which the implementation determines what other locales are available is implementation defined. -c Write the names of selected locale categories; see 4.34.6.1. -k Write the names and values of selected keywords. The implementation may omit values for some keywords; see 4.34.4. -m Write names of available charmaps; see 2.4.1. 1 4.34.4 Operands The following operand shall be supported by the implementation: _n_a_m_e The name of a locale category as defined in 2.5, the name of a keyword in a locale category, or the reserved name charmap. The named category or keyword shall be selected for output. If a single _n_a_m_e represents both a locale category name and a keyword name in the current locale, the results are unspecified. Otherwise, both category and keyword names can be specified as _n_a_m_e operands, in any sequence. It is implementation defined whether any keyword values are written for the categories LC_CTYPE and LC_COLLATE. 4.34.5 External Influences 4.34.5.1 Standard Input None. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.34 locale - Get locale-specific information 571 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX 4.34.5.2 Input Files None. 4.34.5.3 Environment Variables The following environment variables shall affect the execution of locale: LANG This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_) do not specify a locale. See 2.6. LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_. LC_CTYPE This variable shall determine the locale for the interpretation of sequences of bytes of text data as characters (e.g., single- versus multibyte characters in arguments). LC_MESSAGES This variable shall determine the language in which messages should be written. The LANG and LC_* environment variables shall specify the current locale environment to be written out; they shall be used if the -a option is not specified. 4.34.5.4 Asynchronous Events Default. 4.34.6 External Effects 4.34.6.1 Standard Output If locale is invoked without any options or operands, the names and values of the LANG and LC_* environment variables described in this standard shall be written to the standard output, one variable per line, with LANG first, and each line using the following format. Only those variables set in the environment and not overridden by LC_ALL shall be written using this format: "%s=%s\n", <_v_a_r_i_a_b_l_e__n_a_m_e>, <_v_a_l_u_e> Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 572 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 The names of those LC_* variables associated with locale categories defined in this standard that are not set in the environment or are overridden by LC_ALL shall be written in the following format: "%s=\"%s\"\n", <_v_a_r_i_a_b_l_e__n_a_m_e>, <_i_m_p_l_i_e_d _v_a_l_u_e> The <_i_m_p_l_i_e_d _v_a_l_u_e> shall be the name of the locale that has been selected for that category by the implementation, based on the values in LANG and LC_ALL, as described in 2.6. The <_v_a_l_u_e> and <_i_m_p_l_i_e_d _v_a_l_u_e> shown above shall be properly quoted for 1 possible later re-entry to the shell. The <_v_a_l_u_e> shall not be quoted 1 using double-quotes (so that it can be distinguished by the user from the 1 <_i_m_p_l_i_e_d _v_a_l_u_e> case, which always requires double-quotes). 1 The LC_ALL variable shall be written last, using the first format shown 1 above. If it is not set, it shall be written as: "LC_ALL=\n" If any arguments are specified: (1) If the -a option is specified, the names of all the public locales shall be written, each in the following format: "%s\n", <_l_o_c_a_l_e _n_a_m_e> (2) If the -c option is specified, the name(s) of all selected categories shall be written, each in the following format: "%s\n", <_c_a_t_e_g_o_r_y _n_a_m_e> If keywords are also selected for writing (see following items), the category name output shall precede the keyword output for that category. If the -c option is not specified, the names of the categories 2 shall not be written; only the keywords, as selected by the _n_a_m_e 2 operand, shall be written. 2 (3) If the -k option is specified, the name(s) and value(s) of selected keywords shall be written. If a value is nonnumeric, it shall be written in the following format: "%s=\"%s\"\n", <_k_e_y_w_o_r_d _n_a_m_e>, <_k_e_y_w_o_r_d _v_a_l_u_e> If the keyword was charmap, the name of the charmap (if any) that was specified via the localedef -f option when the locale was created shall be written, with the word charmap as <_k_e_y_w_o_r_d Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.34 locale - Get locale-specific information 573 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX _n_a_m_e>. If a value is numeric, it shall be written in one of the following formats: "%s=%d\n", <_k_e_y_w_o_r_d _n_a_m_e>, <_k_e_y_w_o_r_d _v_a_l_u_e> "%s=%c%o\n", <_k_e_y_w_o_r_d _n_a_m_e>, <_e_s_c_a_p_e _c_h_a_r_a_c_t_e_r>, <_k_e_y_w_o_r_d _v_a_l_u_e> "%s=%cx%x\n", <_k_e_y_w_o_r_d _n_a_m_e>, <_e_s_c_a_p_e _c_h_a_r_a_c_t_e_r>, <_k_e_y_w_o_r_d _v_a_l_u_e> where the <_e_s_c_a_p_e _c_h_a_r_a_c_t_e_r> is that identified by the escape_char keyword in the current locale; see 2.5.2. Compound keyword values (list entries) shall be separated in the output by semicolons. When included in keyword values, the semicolon, the double-quote, the backslash, and any control character shall be preceded (escaped) with the escape character. (4) If the -k option is not specified, selected keyword values shall be written, each in the following format: "%s\n", <_k_e_y_w_o_r_d _v_a_l_u_e> If the keyword was charmap, the name of the charmap (if any) that was specified via the localedef -f option when the locale was created shall be written. (5) If the -m option is specified, then a list of all available charmaps shall be written, each in the format "%s\n", <_c_h_a_r_m_a_p> where <_c_h_a_r_m_a_p> is in a format suitable for use as the option- argument to the localedef -f option. 4.34.6.2 Standard Error Used only for diagnostic messages. 4.34.6.3 Output Files None. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 574 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 4.34.7 Extended Description None. 4.34.8 Exit Status The locale utility shall exit with one of the following values: 0 All the requested information was found and output successfully. >0 An error occurred. 4.34.9 Consequences of Errors Default. BEGIN_RATIONALE 4.34.10 Rationale. (_T_h_i_s _s_u_b_c_l_a_u_s_e _i_s _n_o_t _a _p_a_r_t _o_f _P_1_0_0_3._2) _E_x_a_m_p_l_e_s_,__U_s_a_g_e In the following examples, the assumption is that locale environment variables are set as follows: LANG=locale_x LC_COLLATE=locale_y The command: locale would result in the following output: LANG=locale_x 1 LC_CTYPE="locale_x" LC_COLLATE=locale_y LC_TIME="locale_x" LC_NUMERIC="locale_x" LC_MONETARY="locale_x" LC_MESSAGES="locale_x" LC_ALL= The order of presentation of the categories is not specified by this standard. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.34 locale - Get locale-specific information 575 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX The command LC_ALL=POSIX locale -ck decimal_point would produce: LC_NUMERIC decimal_point="." The following command shows an application of locale to determine whether a user supplied response is affirmative: if printf "%s\n" "$response" | grep -Eq "$(locale yesexpr)" then affirmative processing goes here else nonaffirmative processing goes here fi If the LANG environment variable is not set or set to an empty value, or one of the LC_* environment variables is set to an unrecognized value, the actual locales assumed (if any) are implementation defined as described in 2.6. Implementations are not required to write out the actual values for keywords in the categories LC_CTYPE and LC_COLLATE; however, they must write out the categories (allowing an application to determine, e.g., which character classes are available). _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e This command was added in Draft 9 to resolve objections to the lack of a way for applications to determine what locales are available, a way to examine the contents of existing public locales, a way to retrieve specific locale items, and a way to recognize affirmative and negative responses in an international environment. In Draft 10 it was cut back considerably in answer to balloting objections about its complexity and requirement of features not useful for application programs. The format for the no-arguments case was expanded to show the implied values of the categories as an aid to the novice user; the output was of little more value than that from env. Based on the questionable value in a shell script of getting an entire array of characters back, and the problem of returning a collation description that makes sense, short of a complete localedef source, the output from requests for categories LC_CTYPE and LC_COLLATE has been made implementation defined. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 576 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 The -m option has been added to allow applications to query for the existence of charmaps. The output is a list of the charmaps (implementation-supplied and user-supplied, if any) on the system. The -c option was included for readability when more than one category is 2 selected (e.g., via more than one keyword name or via a category name). 2 It is valid both with and without the -k option. 2 The charmap keyword, which returns the name of the charmap (if any) that was used when the current locale was created, was introduced to allow applications needing the information to retrieve it. END_RATIONALE 4.35 localedef - Define locale environment 4.35.1 Synopsis localedef [-c] [-f _c_h_a_r_m_a_p] [-i _s_o_u_r_c_e_f_i_l_e] _n_a_m_e 4.35.2 Description The localedef utility shall convert source definitions for locale categories into a format usable by the functions and utilities whose operational behavior is determined by the setting of the locale environment variables defined in 2.5. It is implementation defined whether users shall have the capability to create new locales, in addition to those supplied by the implementation. If the symbolic constant {POSIX2_LOCALEDEF} is defined, then the system supports the creation of new locales. In a system not supporting this capability, the localedef utility shall terminate with an exit code of 3. The utility shall read source definitions for one or more locale categories belonging to the same locale from the file named in the -i option (if specified) or from standard input. The _n_a_m_e operand identifies the target locale. The utility shall support the creation of _p_u_b_l_i_c, or generally accessible locales, as well as _p_r_i_v_a_t_e, or restricted-access locales. Implementations may restrict the capability to create or modify public locales to users with the appropriate privileges. Each category source definition shall be identified by the corresponding environment variable name and terminated by an END _c_a_t_e_g_o_r_y-_n_a_m_e statement. The following categories shall be supported. In addition, Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.35 localedef - Define locale environment 577 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX the input may contain source for implementation-defined categories. LC_CTYPE Defines character classification and case conversion. LC_COLLATE Defines collation rules. LC_MONETARY Defines the format and symbols used in formatting of monetary information. LC_NUMERIC Defines the decimal delimiter, grouping, and grouping symbol for nonmonetary numeric editing. LC_TIME Defines the format and content of date and time information. LC_MESSAGES Defines the format and values of affirmative and negative responses. 4.35.3 Options The localedef utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following options shall be supported by the implementation: -c Create permanent output even if warning messages have been issued. -f _c_h_a_r_m_a_p Specify the pathname of a file containing a mapping of character symbols and collating element symbols to actual character encodings. The format of the _c_h_a_r_m_a_p is described under 2.4.1. This option shall be specified if symbolic names (other than collating symbols defined in a collating-symbol keyword) are used. If the -f option is not present, an implementation-defined default character mapping file shall be used. 2 -i _i_n_p_u_t_f_i_l_e The pathname of a file containing the source definitions. If this option is not present, source definitions shall be read from standard input. The format of the _i_n_p_u_t_f_i_l_e is described in 2.5.2. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 578 4 Execution Environment Utilities Part 2: SHELL AND UTILITIES P1003.2/D11.2 4.35.4 Operands The following operand shall be supported by the implementation: _n_a_m_e Identifies the locale. See 2.5 for a description of the use of this name. If the name contains one or more slash characters, _n_a_m_e shall be interpreted as a pathname where the created locale definition(s) shall be stored. If _n_a_m_e does not contain any slash characters, the interpretation of the name is implementation defined and the locale shall be public. This capability may be restricted to users with appropriate privileges. 4.35.5 External Influences 4.35.5.1 Standard Input Unless the -i option is specified, the standard input shall be a text file containing one or more locale category source definitions, as described in 2.5.2. When lines are continued using the escape character 1 mechanism, there is no limit to the length of the accumulated continued 1 line. 1 4.35.5.2 Input Files The character set mapping file specified as the _c_h_a_r_m_a_p option-argument is described under 2.4.1. If a locale category source definition contains a copy statement, as defined in 2.5.2, and the copy statement names a valid, existing locale, then localedef shall behave as if the source definition had contained a valid category source definition for the named locale. 4.35.5.3 Environment Variables The following environment variables shall affect the execution of localedef: LANG This variable shall determine the locale to use for the locale categories when both LC_ALL and the corresponding environment variable (beginning with LC_) do not specify a locale. See 2.6. LC_ALL This variable shall determine the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_. and LC_* variables as described in 2.6. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 4.35 localedef - Define locale environment 579 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX LC_COLLATE (This variable shall have no affect on localedef; the POSIX Locale shall be used for this category.) LC_CTYPE This variable shall determine the locale for the interpretation of sequences of bytes of argument data as characters (e.g., single- versus multibyte characters). This variable shall have no affect on the processing of localedef input data; the POSIX Locale shall be used for this purpose, regardless of the value of this variable. LC_MESSAGES This variable shall determine the language in which messages should be written. 4.35.5.4 Asynchronous Events Default. 4.35.6 External Effects 4.35.6.1 Standard Output The utility shall report all categories successfully processed, in an unspecified format. 4.35.6.2 Standard Error Used only for diagnostic messages. 4.35.6.3 Output Files The format of the created output is unspecified. If the _n_a_m_e operand does not contain a slash, the existence of an output file for the locale is unspecified. 4.35.7 Extended Description None. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 580 4 Execution Environment Utilities