diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/ar.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/ar.1p | 729 |
1 files changed, 729 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/ar.1p b/man-pages-posix-2017/man1p/ar.1p new file mode 100644 index 0000000..4b41b7c --- /dev/null +++ b/man-pages-posix-2017/man1p/ar.1p @@ -0,0 +1,729 @@ +'\" et +.TH AR "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ar +\(em create and maintain library archives +.SH SYNOPSIS +.LP +.nf +ar -d \fB[\fR-v\fB] \fIarchive file\fR... +.P +ar -m \fB[\fR-v\fB] \fIarchive file\fR... +ar -m -a \fB[\fR-v\fB] \fIposname archive file\fR... +ar -m -b \fB[\fR-v\fB] \fIposname archive file\fR... +ar -m -i \fB[\fR-v\fB] \fIposname archive file\fR... +.P +ar -p \fB[\fR-v\fB] [\fR-s\fB] \fIarchive\fB [\fIfile\fR...\fB]\fR +.P +ar -q \fB[\fR-cv\fB] \fIarchive file\fR... +.P +ar -r \fB[\fR-cuv\fB] \fIarchive file\fR... +.P +ar -r -a \fB[\fR-cuv\fB] \fIposname archive file\fR... +ar -r -b \fB[\fR-cuv\fB] \fIposname archive file\fR... +ar -r -i \fB[\fR-cuv\fB] \fIposname archive file\fR... +.P +ar -t \fB[\fR-v\fB] [\fR-s\fB] \fIarchive \fB[\fIfile\fR...\fB]\fR +.P +ar -x \fB[\fR-v\fB] [\fR-sCT\fB] \fIarchive \fB[\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +.P +The +.IR ar +utility is part of the Software Development Utilities option. +.P +The +.IR 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 in an archive 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 +.IR c99 +and +.IR fort77 ). +When some of the archived files are not valid object files, the +suitability of the archive for library use is undefined. +If an archive consists entirely of printable files, the entire +archive shall be printable. +.P +When +.IR ar +creates an archive, it creates administrative information indicating +whether a symbol table is present in the archive. When there is at +least one object file that +.IR ar +recognizes as such in the archive, an archive symbol table shall be +created in the archive and maintained by +.IR ar ; +it is used by the link editor to search the archive. Whenever the +.IR ar +utility is used to create or update the contents of such an archive, +the symbol table shall be rebuilt. The +.BR \-s +option shall force the symbol table to be rebuilt. +.P +All +.IR file +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 +.IR file +operands to the names of files in archives shall be performed by +comparing the last component of the operand to the name of the file +in the archive. +.P +It is unspecified whether multiple files in the archive may be +identically named. In the case of such files, however, each +.IR file +and +.IR posname +operand shall match only the first file in the archive having a name +that is the same as the last component of the operand. +.SH OPTIONS +The +.IR ar +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +except for Guideline 9. +.P +The following options shall be supported: +.IP "\fB\-a\fP" 10 +Position new files in the archive after the file named by the +.IR posname +operand. +.IP "\fB\-b\fP" 10 +Position new files in the archive before the file named by the +.IR posname +operand. +.IP "\fB\-c\fP" 10 +Suppress the diagnostic message that is written to standard error by +default when the archive +.IR archive +is created. +.IP "\fB\-C\fP" 10 +Prevent extracted files from replacing like-named files in the +file system. This option is useful when +.BR \-T +is also used, to prevent truncated filenames from replacing files with +the same prefix. +.IP "\fB\-d\fP" 10 +Delete one or more +.IR file s +from +.IR archive . +.IP "\fB\-i\fP" 10 +Position new files in the archive before the file in the archive +named by the +.IR posname +operand (equivalent to +.BR \-b ). +.IP "\fB\-m\fP" 10 +Move the named files in the archive. The +.BR \-a , +.BR \-b , +or +.BR \-i +options with the +.IR posname +operand indicate the position; otherwise, move the names files in the +archive to the end of the archive. +.IP "\fB\-p\fP" 10 +Write the contents of the +.IR file s +in the archive named by +.IR file +operands from +.IR archive +to the standard output. If no +.IR file +operands are specified, the contents of all files in the archive shall +be written in the order of the archive. +.IP "\fB\-q\fP" 10 +Append the named files to the end of the archive. In this case +.IR ar +does not check whether the added files are already in the archive. +This is useful to bypass the searching otherwise done when creating a +large archive piece by piece. +.IP "\fB\-r\fP" 10 +Replace or add +.IR file s +to +.IR archive . +If the archive named by +.IR archive +does not exist, a new archive shall be created and a diagnostic message +shall be written to standard error (unless the +.BR \-c +option is specified). If no +.IR file s +are specified and the +.IR archive +exists, the results are undefined. Files that replace existing files in +the archive shall not change the order of the archive. Files that do +not replace existing files in the archive shall be appended to the +archive +unless a +.BR \-a , +.BR \-b , +or +.BR \-i +option specifies another position. +.IP "\fB\-s\fP" 10 +Force the regeneration of the archive symbol table even if +.IR ar +is not invoked with an option that modifies the archive contents. This +option is useful to restore the archive symbol table after it has been +stripped; see +.IR strip . +.IP "\fB\-t\fP" 10 +Write a table of contents of +.IR archive +to the standard output. Only the files specified by the +.IR file +operands shall be included in the written list. If no +.IR file +operands are specified, all files in +.IR archive +shall be included in the order of the archive. +.IP "\fB\-T\fP" 10 +Allow filename truncation of extracted files whose archive names are +longer than the file system can support. By default, extracting a file +with a name that is too long shall be an error; a diagnostic message +shall be written and the file shall not be extracted. +.IP "\fB\-u\fP" 10 +Update older files in the archive. When used with the +.BR \-r +option, files in the archive shall be replaced only if the +corresponding +.IR file +has a modification time that is at least as new as the modification +time of the file in the archive. +.IP "\fB\-v\fP" 10 +Give verbose output. When used with the option characters +.BR \-d , +.BR \-r , +or +.BR \-x , +write a detailed file-by-file description of the archive creation and +maintenance activity, as described in the STDOUT section. +.RS 10 +.P +When used with +.BR \-p , +write the name of the file in the archive to the standard output before +writing the file in the archive itself to the standard output, as +described in the STDOUT section. +.P +When used with +.BR \-t , +include a long listing of information about the files in the archive, +as described in the STDOUT section. +.RE +.IP "\fB\-x\fP" 10 +Extract the files in the archive named by the +.IR file +operands from +.IR archive . +The contents of the archive shall not be changed. If no +.IR file +operands are given, all files in the archive shall be extracted. The +modification time of each file extracted shall be set to the time the +file is extracted from the archive. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIarchive\fR" 10 +A pathname of the archive. +.IP "\fIfile\fR" 10 +A pathname. Only the last component shall be used when comparing +against the names of files in the archive. If two or more +.IR file +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. +.IP "\fIposname\fR" 10 +The name of a file in the archive, used for relative positioning; see +options +.BR \-m +and +.BR \-r . +.SH STDIN +Not used. +.SH "INPUT FILES" +The archive named by +.IR archive +shall be a file in the format created by +.IR ar +.BR \-r . +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR ar : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fILC_TIME\fP" 10 +Determine the format and content for date and time strings written by +.IR ar +.BR \-tv . +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fITMPDIR\fP" 10 +Determine the pathname that overrides the default directory for +temporary files, if any. +.IP "\fITZ\fP" 10 +Determine the timezone used to calculate date and time strings written +by +.IR ar +.BR \-tv . +If +.IR TZ +is unset or null, an unspecified default timezone shall be used. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \-d +option is used with the +.BR \-v +option, the standard output format shall be: +.sp +.RS 4 +.nf + +"d - %s\en", <\fIfile\fR> +.fi +.P +.RE +.P +where +.IR file +is the operand specified on the command line. +.P +If the +.BR \-p +option is used with the +.BR \-v +option, +.IR ar +shall precede the contents of each file with: +.sp +.RS 4 +.nf + +"\en<%s>\en\en", <\fIfile\fR> +.fi +.P +.RE +.P +where +.IR file +is the operand specified on the command line, if +.IR file +operands were specified, and the name of the file in the archive if +they were not. +.P +If the +.BR \-r +option is used with the +.BR \-v +option: +.IP " *" 4 +If +.IR file +is already in the archive, the standard output format shall be: +.RS 4 +.sp +.RS 4 +.nf + +"r - %s\en", <\fIfile\fR> +.fi +.P +.RE +.P +where <\fIfile\fP> is the operand specified on the command line. +.RE +.IP " *" 4 +If +.IR file +is not already in the archive, the standard output format shall be: +.RS 4 +.sp +.RS 4 +.nf + +"a - %s\en", <\fIfile\fR> +.fi +.P +.RE +.P +where <\fIfile\fP> is the operand specified on the command line. +.RE +.P +If the +.BR \-t +option is used, +.IR ar +shall write the names of the files in the archive to the standard +output in the format: +.sp +.RS 4 +.nf + +"%s\en", <\fIfile\fR> +.fi +.P +.RE +.P +where +.IR file +is the operand specified on the command line, if +.IR file +operands were specified, or the name of the file in the archive if they +were not. +.P +If the +.BR \-t +option is used with the +.BR \-v +option, the standard output format shall be: +.sp +.RS 4 +.nf + +"%s %u/%u %u %s %d %d:%d %d %s\en", <\fImember mode\fR>, <\fIuser ID\fR>, + <\fIgroup ID\fR>, <\fInumber of bytes in member\fR>, + <\fIabbreviated month\fR>, <\fIday-of-month\fR>, <\fIhour\fR>, + <\fIminute\fR>, <\fIyear\fR>, <\fIfile\fR> +.fi +.P +.RE +.P +where: +.IP "<\fIfile\fR>" 10 +Shall be the operand specified on the command line, if +.IR file +operands were specified, or the name of the file in the archive if they +were not. +.IP "<\fImember\ mode\fR>" 10 +.br +Shall be formatted the same as the <\fIfile\ mode\fR> string defined in +the STDOUT section of +.IR ls , +except that the first character, the <\fIentry\ type\fR>, is not used; +the string represents the file mode of the file in the archive at the +time it was added to or replaced in the archive. +.br +.P +The following represent the last-modification time of a file when it +was most recently added to or replaced in the archive: +.IP "<\fIabbreviated\ month\fR>" 10 +.br +Equivalent to the format of the +.BR %b +conversion specification format in +.IR date . +.IP "<\fIday-of-month\fR>" 10 +.br +Equivalent to the format of the +.BR %e +conversion specification format in +.IR date . +.IP "<\fIhour\fR>" 10 +Equivalent to the format of the +.BR %H +conversion specification format in +.IR date . +.IP "<\fIminute\fR>" 10 +Equivalent to the format of the +.BR %M +conversion specification format in +.IR date . +.IP "<\fIyear\fR>" 10 +Equivalent to the format of the +.BR %Y +conversion specification format in +.IR date . +.P +When +.IR 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. +.P +If the +.BR \-x +option is used with the +.BR \-v +option, the standard output format shall be: +.sp +.RS 4 +.nf + +"x - %s\en", <\fIfile\fR> +.fi +.P +.RE +.P +where +.IR file +is the operand specified on the command line, if +.IR file +operands were specified, or the name of the file in the archive if they +were not. +.SH STDERR +The standard error shall be used only for diagnostic messages. +The diagnostic message about creating a new archive when +.BR \-c +is not specified shall not modify the exit status. +.SH "OUTPUT FILES" +Archives are files with unspecified formats. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +None. +.SH EXAMPLES +None. +.SH RATIONALE +The archive format is not described. It is recognized that there are +several known +.IR ar +formats, which are not compatible. The +.IR ar +utility is included, however, to allow creation of archives that +are intended for use only on one machine. The archive 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 +.IR ar . +.P +Utilities such as +.IR pax +(and its forebears +.IR tar +and +.IR cpio ) +also provide portable ``archives''. This is a not a duplication; the +.IR ar +utility is included to provide an interface primarily for +.IR make +and the compilers, based on a historical model. +.P +In historical implementations, the +.BR \-q +option (available on XSI-conforming systems) is known to execute +quickly because +.IR ar +does not check on 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. These remarks may but need not +remain true for a brand new implementation of this utility; hence, +these remarks have been moved into the RATIONALE. +.P +BSD implementations historically required applications to provide the +.BR \-s +option whenever the archive was supposed to contain a symbol table. +As in this volume of POSIX.1\(hy2017, System V historically creates or updates an archive symbol +table whenever an object file is removed from, added to, or updated +in the archive. +.P +The OPERANDS section 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, this volume of POSIX.1\(hy2017 makes the requirement +explicit to avoid misunderstandings. +.P +According to the System V documentation, the options +.BR \-dmpqrtx +are not required to begin with a +<hyphen-minus> +(\c +.BR '\-' ). +This volume of POSIX.1\(hy2017 requires that a conforming application use the leading +<hyphen-minus>. +.P +The archive format used by the 4.4 BSD implementation is documented in +this RATIONALE as an example: +.sp +.RS +A file created by +.IR ar +begins with the ``magic'' string +.BR \(dq!<arch>\en\(dq . +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. +.P +The header is made up of six ASCII fields, followed by a two-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. +.P +The modification time is the file +.IR st_mtime +field. The user and group IDs are the file +.IR st_uid +and +.IR st_gid +fields. The file mode is the file +.IR st_mode +field. The file size is the file +.IR st_size +field. The two-byte trailer is the string +.BR \(dq`<newline>\(dq . +.P +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 +.BR \(dq#1/\(dq +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. +.P +Any unused characters in any of these fields are written as +<space> +characters. If any fields are their particular maximum number of +characters in length, there is no separation between the fields. +.P +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 +<newline>, +although the size in the header does not reflect this. +.RE +.P +The +.IR ar +utility description requires that (when all its members are valid +object files) +.IR 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, +.IR ar +must provide it; however, +.IR ar +does not require a symbol table. +.P +The BSD +.BR \-o +option was omitted. It is a rare conforming application that uses +.IR ar +to extract object code from a library with concern for its modification +time, since this can only be of importance to +.IR 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. +.P +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 historical practice for most implementations, but is also a +reasonable expectation. +.P +Consideration was given to changing the output format of +.IR ar +.BR \-tv +to the same format as the output of +.IR ls +.BR \-l . +This would have made parsing the output of +.IR ar +the same as that of +.IR ls . +This was rejected in part because the current +.IR ar +format is commonly used and changes would break historical usage. +Second, +.IR ar +gives the user ID and group ID in numeric format separated by a +<slash>. +Changing this to be the user name and group name would not be correct +if the archive were moved to a machine that contained a different user +database. Since +.IR ar +cannot know whether the archive was generated on the same machine, +it cannot tell what to report. +.P +The text on the +.BR \-ur +option combination is historical practice\(emsince one filename can +easily represent two different files (for example, +.BR /a/foo +and +.BR /b/foo ), +it is reasonable to replace the file in the archive even when the +modification time in the archive is identical to that in the file +system. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIc99\fR\^", +.IR "\fIdate\fR\^", +.IR "\fIfort77\fR\^", +.IR "\fIpax\fR\^", +.IR "\fIstrip\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB<unistd.h>\fP", +description of +{POSIX_NO_TRUNC} +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |