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] P1003.2/D11.2 Section 6: Software Development Utilities Option This section describes utilities used for the development of applications, including compilation or translation of source code, the creation and maintenance of library archives, and the maintenance of groups of interdependent programs. The utilities described in this section may be provided by the conforming system; however, any system claiming conformance to the Software Development Utilities Option shall provide all of the utilities described here. 6.1 ar - Create and maintain library archives 6.1.1 Synopsis ar -d [-v] _a_r_c_h_i_v_e _f_i_l_e ... ar -p [-v] _a_r_c_h_i_v_e [_f_i_l_e ...] ar -r [-cuv] _a_r_c_h_i_v_e _f_i_l_e ... ar -t [-v] _a_r_c_h_i_v_e [_f_i_l_e ...] ar -x [-v] _a_r_c_h_i_v_e [_f_i_l_e ...] 6.1.2 Description The ar utility can be used to create and maintain groups of files combined into an archive. Once an archive has been created, new files can be added, and existing files can be extracted, deleted, or replaced. When an archive consists entirely of valid object files, the implementation shall format the archive so that it is usable as a library for link editing (see A.1 and C.2). When some of the archived files are not valid object files, the suitability of the archive for library use is undefined. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 6.1 ar - Create and maintain library archives 809 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX All _f_i_l_e operands can be pathnames. However, files within archives shall be named by a filename, which is the last component of the pathname used when the file was entered into the archive. The comparison of _f_i_l_e operands to the names of files in archives shall be performed by comparing the last component of the operand to the name of the archive file. It is unspecified whether multiple files in the archive may be identically named. In the case of such files, however, each _f_i_l_e operand shall match only the first archive file having a name that is the same as the last component of the _f_i_l_e operand. 6.1.3 Options The ar utility shall conform to the utility argument syntax guidelines described in 2.10.2. The following options shall be supported by the implementation: -c Suppress the diagnostic message that is written to standard error by default when the archive file _a_r_c_h_i_v_e is created. -d Delete _f_i_l_e(s) from _a_r_c_h_i_v_e. -p Write the contents of the _f_i_l_e(s) from _a_r_c_h_i_v_e to the standard output. If no _f_i_l_e(s) are specified, the contents of all files in the archive shall be written in the order of the archive. -r Replace or add _f_i_l_e(s) to _a_r_c_h_i_v_e. If the archive named by _a_r_c_h_i_v_e does not exist, a new archive file shall be created and a diagnostic message shall be written to standard error (unless the -c option is specified). If no _f_i_l_e(s) are specified and the _a_r_c_h_i_v_e exists, the results are undefined. Files that replace existing files shall not change the order of the archive. Files that do not replace existing files shall be appended to the archive. -t Write a table of contents of _a_r_c_h_i_v_e to the standard output. The files specified by the _f_i_l_e operands shall be included in the written list. If no _f_i_l_e operands are specified, all files in _a_r_c_h_i_v_e shall be included in the order of the archive. -u Update older files. When used with the -r option, files within the archive will be replaced only if the corresponding _f_i_l_e has a modification time that is at Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 810 6 Software Development Utilities Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 least as new as the modification time of the file within the archive. -v Give verbose output. When used with the option characters -d, -r, or -x, write a detailed file-by-file description of the archive creation and maintenance activity, as described in 6.1.6.1. When used with -p, write the name of the file to the standard output before writing the file itself to the standard output, as described in 6.1.6.1. When used with -t, include a long listing of information about the files within the archive, as described in 6.1.6.1. -x Extract the files named by the _f_i_l_e operands from _a_r_c_h_i_v_e. The contents of the archive file shall not be changed. If no _f_i_l_e operands are given, all files in the archive shall be extracted. If the filename of a file extracted from the archive is longer than that supported in the directory to which it is being extracted, the results are undefined. The modification time of each file extracted shall be set to the time the file is extracted from the archive. 6.1.4 Operands The following operands shall be supported by the implementation: _a_r_c_h_i_v_e A pathname of the archive file. _f_i_l_e A pathname. Only the last component shall be used when comparing against the names of files in the archive. If two or more _f_i_l_e operands have the same last pathname component (basename), the results are unspecified. The implementation's archive format shall not truncate valid filenames of files added to, or replaced in, the archive. 6.1.5 External Influences 6.1.5.1 Standard Input None. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 6.1 ar - Create and maintain library archives 811 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX 6.1.5.2 Input Files The input file named by _a_r_c_h_i_v_e shall be a file in the format created by ar -r. 6.1.5.3 Environment Variables The following environment variables shall affect the execution of ar: 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. LC_TIME This variable shall determine the format and content for date and time strings written by ar. 6.1.5.4 Asynchronous Events Default. 6.1.6 External Effects 6.1.6.1 Standard Output If the -d option is used with the -v option, the standard output format is: "d - %s\n", <_f_i_l_e> where _f_i_l_e is the operand specified on the command line. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 812 6 Software Development Utilities Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 If the -p option is used with the -v option, ar shall precede the contents of each file with: "\n<%s>\n\n", <_f_i_l_e> where _f_i_l_e is the operand specified on the command line, if _f_i_l_e operands were specified, and the name of the file in the archive if they were not. If the -r option is used with the -v option, and _f_i_l_e is already in the archive, the standard output format is: "r - %s\n", <_f_i_l_e> where _f_i_l_e is the operand specified on the command line. If _f_i_l_e is being added to the archive with the -r option, the standard output format is: "a - %s\n", <_f_i_l_e> where _f_i_l_e is the operand specified on the command line. If the -t option is used, ar writes the names of the files to the standard output in the format: "%s\n", <_f_i_l_e> where _f_i_l_e is the operand specified on the command line, if _f_i_l_e operands were specified, or the name of the file in the archive if they were not. If the -t option is used with the -v option, the standard output format is: "%s %u/%u %u %s %d %d:%d %d %s\n", <_m_e_m_b_e_r _m_o_d_e>, <_u_s_e_r _I_D>, <_g_r_o_u_p _I_D>, <_n_u_m_b_e_r _o_f _b_y_t_e_s _i_n _m_e_m_b_e_r>, <_a_b_b_r_e_v_i_a_t_e_d _m_o_n_t_h>, <_d_a_y-_o_f-_m_o_n_t_h>, <_h_o_u_r>, <_m_i_n_u_t_e>, <_y_e_a_r>, <_f_i_l_e> Where: _f_i_l_e shall be the operand specified on the command line, if _f_i_l_e operands were specified, or the name of the file in the archive if they were not. <_m_e_m_b_e_r _m_o_d_e> shall be formatted the same as the <_f_i_l_e _m_o_d_e> string defined in 4.39.6.1 (Standard Output of ls), except that the first character, the <_e_n_t_r_y _t_y_p_e>, is not used; the string represents the file mode of the archive member at the time it was added to, or replaced in, the archive. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 6.1 ar - Create and maintain library archives 813 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX The following represent the last-modification time of a file when it was most recently added to or replaced in the archive: <_a_b_b_r_e_v_i_a_t_e_d _m_o_n_t_h> shall be equivalent to the %b format in date (see 4.15). <_d_a_y-_o_f-_m_o_n_t_h> shall be equivalent to the %e format in date. <_h_o_u_r> shall be equivalent to the %H format in date. <_m_i_n_u_t_e> shall be equivalent to the %M format in date. <_y_e_a_r> shall be equivalent to the %Y format in date. When LC_TIME does not specify the POSIX Locale, a different format and order of presentation of these fields relative to each other may be used in a format appropriate in the specified locale. If the -x option is used with the -v option, the standard output format is: "x - %s\n", <_f_i_l_e> where _f_i_l_e is the operand specified on the command line, if _f_i_l_e operands were specified, or the name of the file in the archive if they were not. 6.1.6.2 Standard Error Used only for diagnostic messages. The diagnostic message about creating a new archive when -c is not specified shall not modify the exit status. 6.1.6.3 Output Files Archives are files with unspecified formats. 6.1.7 Extended Description None. 6.1.8 Exit Status The ar utility shall exit with one of the following values: 0 Successful completion. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 814 6 Software Development Utilities Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 >0 An error occurred. 6.1.9 Consequences of Errors Default. BEGIN_RATIONALE 6.1.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 The archive format is not described. It is recognized that there are several known ar formats, which are not compatible. The ar utility is being included, however, to allow creation of archives that are intended for use only on the same machine. The archive file is specified as a file and it can be moved as a file. This does allow an archive to be moved from one machine to another machine that uses the same implementation of ar. Utilities such as pax (and its forebears tar and cpio) also provide 1 portable ``archives.'' This is a not a duplication; the ar interface is included in the standard to provide an interface primarily for make and the compilers, based on a historical model. In historical implementations, the -q option is known to execute quickly because ar does not check whether the added members are already in the archive. This is useful to bypass the searching otherwise done when creating a large archive piece-by-piece. The remarks may or may not hold true for a brand-new POSIX.2 implementation; and hence, these remarks have been moved out of the specification and into the Rationale. Likewise, historical implementations maintain a symbol table to speed searches, particularly when the archive contains object files. However, future implementors may or may not use a symbol table, and the -s option was removed from this clause to permit implementors freedom of choice. Instead, the requirement that archive libraries be suitable for link editing was added to ensure the intended functionality. Systems such as System V maintain the symbol table without requiring the use of -s, so adding -s (even if it were worded as allowing a no-op) would essentially require all portable applications to use it in all invocations involving libraries. The Operands subclause requires what might seem to be true without specifying it: the archive cannot truncate the filenames below {NAME_MAX}. Some historical implementations do so, however, causing unexpected results for the application. Therefore, POSIX.2 makes the Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 6.1 ar - Create and maintain library archives 815 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX requirement explicit to avoid misunderstandings. According to the System V documentation, the options -dmpqrtx are not required to begin with a hyphen ( - ). POSIX.2 requires that a conforming application use the leading hyphen. When extracting files with long filenames into a file system that supports only shorter filenames, an undefined condition occurs. Typical implementation actions might be one of the following: - Extract and truncate the filename only when an existing file would not be overlaid. - Extract and truncate the filename and overlay an existing file only if some extension such as another command-line option were used to override this safety feature. - Refuse to extract any files unless an extension overrode the default. The archive format used by the 4.4BSD implementation is documented in the rationale as an example: A file created by ar begins with the ``magic'' string ``!\n''. The rest of the archive is made up of objects, each of which is composed of a header for a file, a possible filename, and the file contents. The header is portable between machine architectures, and, if the file contents are printable, the archive is itself printable. The header is made up of six ASCII fields, followed by a two- 2 character trailer. The fields are the object name (16 characters), the file last modification time (12 characters), the user and group IDs (each 6 characters), the file mode (8 characters) and the file size (10 characters). All numeric fields are in decimal, except for the file mode, which is in octal. The modification time is the file _s_t__m_t_i_m_e field. The user and group IDs are the file _s_t__u_i_d and _s_t__g_i_d fields. The file mode is the file _s_t__m_o_d_e field. The file size is the file _s_t__s_i_z_e field. The two-byte trailer is the string ```''. Only the name field has any provision for overflow. If any filename is more than 16 characters in length or contains an embedded space, the string ``#1/'' followed by the ASCII length of the name is written in the name field. The file size (stored in the archive header) is incremented by the length of the name. The name is then written immediately following the archive header. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 816 6 Software Development Utilities Option Part 2: SHELL AND UTILITIES P1003.2/D11.2 Any unused characters in any of these fields are written as characters. If any fields are their particular maximum number of characters in length, there will be no separation between the fields. Objects in the archive are always an even number of bytes long; files that are an odd number of bytes long are padded with a character, although the size in the header does not reflect this. _H_i_s_t_o_r_y__o_f__D_e_c_i_s_i_o_n_s__M_a_d_e The ar utility description requires that (when all its members are valid object files) ar produce an object code library, which the linkage editor can use to extract object modules. If the linkage editor needs a symbol table to permit random access to the archive, ar must provide it; however, ar does not require a symbol table. The historical -m and -q positioning options were omitted, as were the positioning modifiers formerly associated with the -m and -r options, because the two functions of positioning are handled by the ranlib-style (a utility found on some 1 historical systems to create symbol tables within the archive) symbol 1 tables and/or the ability of portable applications to create multiple archives instead of loading from a single archive. Earlier drafts had elaborate descriptions in the Asynchronous Events subclause about how signals were caught and then resent to itself. These were removed in favor of the default case because they are essentially implementation details, unnecessary for the application. Similarly, information about where (and if) temporary files are created was removed from earlier drafts. The BSD -o option was omitted. It is a rare portable application that will use ar to extract object code from a library with concern for its modification time, since this can only be of importance to make. Hence, since this functionality is not deemed important for applications portability, the modification time of the extracted files is set to the current time. There is at least one known implementation (for a small computer) that can accommodate only object files for that system, disallowing mixed object and other files. The ability to handle any type of file is not only existing practice for most implementations, but is also a reasonable expectation. Consideration was given to changing the output format of ar -tv to the same format as the output of ls -l. This would have made parsing the output of ar the same as that of ls. This was rejected in part because the current ar format is commonly used and changes would break existing usage. Second, ar gives the user ID and group ID in numeric format Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 6.1 ar - Create and maintain library archives 817 P1003.2/D11.2 INFORMATION TECHNOLOGY--POSIX separated by a slash. Changing this to be the user name and group name would not be right if the archive were moved to a machine that contained a different user database. Since ar cannot know whether the archive file was generated on the same machine, it cannot tell what to report. The text on the -ur option combination is historical practice--since one filename can easily represent two different files (e.g., /a/foo and /b/foo), it is reasonable to replace the member in the archive even when the modification time in the archive is identical to that in the file system. END_RATIONALE 6.2 make - Maintain, update, and regenerate groups of programs 6.2.1 Synopsis make [-einpqrst] [-f _m_a_k_e_f_i_l_e] ... [ -k | -S ] [_m_a_c_r_o=_n_a_m_e] ... [_t_a_r_g_e_t__n_a_m_e ...] 6.2.2 Description The make utility can be used as a part of software development to update 1 files that are derived from other files. A typical case is one where 1 object files are derived from the corresponding source files. The make 1 utility examines time relationships and updates those derived files 1 (called targets) that have modified times earlier than the modified times 1 of the files (called prerequisites) from which they are derived. A 1 description file (``makefile'') contains a description of the 1 relationships between files, and the commands that must be executed to 1 update the targets to reflect changes in their prerequisites. Each 1 specification, or rule, shall consist of a target, optional 1 prerequisites, and optional commands to be executed when a prerequisite is newer than the target. There are two types of rules: - Inference rules, which have one target name with at least one period (.) and no slash (/) - Target rules, which can have more than one target name In addition, make shall have a collection of built-in macros and inference rules that infer prerequisite relationships to simplify maintenance of programs. Copyright c 1991 IEEE. All rights reserved. This is an unapproved IEEE Standards Draft, subject to change. 818 6 Software Development Utilities Option