1 files changed, 608 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/ar.1p b/man-pages-posix-2003/man1p/ar.1p
new file mode 100644
index 0000000..c66ee18
--- /dev/null
+++ b/man-pages-posix-2003/man1p/ar.1p
@@ -0,0 +1,608 @@
+.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
+.TH "AR" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\" ar 
+.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 \- create and maintain library archives
+.SH SYNOPSIS
+.LP
+\fBar -d\fP\fB[\fP\fB-v\fP\fB]\fP \fIarchive file\fP \fB... \fP
+\fB
+.br
+.sp
+\fP
+.LP
+\fBar -m\fP \fB[\fP\fB-v\fP\fB]\fP \fIarchive file\fP \fB...
+.br
+.sp
+ar -m -a\fP\fB[\fP\fB-v\fP\fB]\fP \fIposname archive file\fP \fB...
+.br
+.sp
+ar -m -b\fP\fB[\fP\fB-v\fP\fB]\fP \fIposname archive file\fP \fB...
+.br
+.sp
+ar -m -i\fP\fB[\fP\fB-v\fP\fB]\fP \fIposname archive file\fP \fB...
+\fP
+\fB
+.br
+.sp
+ar -p\fP\fB[\fP\fB-v\fP\fB][\fP\fB-s\fP\fB]\fP\fIarchive\fP \fB[\fP\fIfile\fP
+\fB\&...\fP\fB]\fP\fB
+.br
+.sp
+\fP
+.LP
+\fBar -q\fP\fB[\fP\fB-cv\fP\fB]\fP \fIarchive file\fP \fB... \fP
+\fB
+.br
+.sp
+ar -r\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIarchive file\fP \fB...
+.br
+.sp
+\fP
+.LP
+\fBar -r -a\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIposname archive file\fP
+\fB\&...
+.br
+.sp
+ar -r -b\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIposname archive file\fP \fB...
+.br
+.sp
+ar -r -i\fP\fB[\fP\fB-cuv\fP\fB]\fP \fIposname archive file\fP \fB...
+\fP
+\fB
+.br
+.sp
+ar -t\fP\fB[\fP\fB-v\fP\fB][\fP\fB-s\fP\fB]\fP\fIarchive\fP \fB[\fP\fIfile\fP
+\fB\&...\fP\fB]\fP\fB
+.br
+.sp
+ar -x\fP\fB[\fP\fB-v\fP\fB][\fP\fB-sCT\fP\fB]\fP\fIarchive\fP \fB[\fP\fIfile\fP
+\fB\&...\fP\fB]\fP\fB
+.br
+\fP
+.SH DESCRIPTION
+.LP
+The \fIar\fP utility is part of the Software Development Utilities
+option.
+.LP
+The \fIar\fP 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
+\fIc99\fP and \fIfort77\fP). 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.
+.LP
+When \fIar\fP 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 \fIar\fP recognizes
+as such in the archive, an archive symbol table shall be
+created in the archive and maintained by \fIar\fP; it is used by the
+link editor to search the archive. Whenever the \fIar\fP
+utility is used to create or update the contents of such an archive,
+the symbol table shall be rebuilt. The \fB-s\fP option shall
+force the symbol table to be rebuilt. 
+.LP
+All \fIfile\fP 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 \fIfile\fP 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.
+.LP
+It is unspecified whether multiple files in the archive may be identically
+named. In the case of such files, however, each
+\fIfile\fP  and \fIposname\fP  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
+.LP
+The \fIar\fP utility shall conform to the Base Definitions volume
+of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
+.LP
+The following options shall be supported:
+.TP 7
+\fB-a\fP
+Position new files in the archive after the file named by the \fIposname\fP
+operand. 
+.TP 7
+\fB-b\fP
+Position new files in the archive before the file named by the \fIposname\fP
+operand. 
+.TP 7
+\fB-c\fP
+Suppress the diagnostic message that is written to standard error
+by default when the archive \fIarchive\fP is created.
+.TP 7
+\fB-C\fP
+Prevent extracted files from replacing like-named files in the file
+system. This option is useful when \fB-T\fP is also used, to
+prevent truncated filenames from replacing files with the same prefix.
+.TP 7
+\fB-d\fP
+Delete one or more \fIfile\fPs from \fIarchive\fP.
+.TP 7
+\fB-i\fP
+Position new files in the archive before the file in the archive named
+by the \fIposname\fP operand (equivalent to \fB-b\fP).
+.TP 7
+\fB-m\fP
+Move the named files in the archive. The \fB-a\fP, \fB-b\fP, or \fB-i\fP
+options with the \fIposname\fP operand indicate the
+position; otherwise, move the names files in the archive to the end
+of the archive. 
+.TP 7
+\fB-p\fP
+Write the contents of the \fIfile\fPs in the archive named by \fIfile\fP
+operands from \fIarchive\fP to the standard output.
+If no \fIfile\fP operands are specified, the contents of all files
+in the archive shall be written in the order of the
+archive.
+.TP 7
+\fB-q\fP
+Append the named files to the end of the archive. In this case \fIar\fP
+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. 
+.TP 7
+\fB-r\fP
+Replace or add \fIfile\fPs to \fIarchive\fP. If the archive named
+by \fIarchive\fP does not exist, a new archive shall be
+created and a diagnostic message shall be written to standard error
+(unless the \fB-c\fP option is specified). If no \fIfile\fPs
+are specified and the \fIarchive\fP 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 \fB-a\fP, \fB-b\fP, or \fB-i\fP option specifies another position.
+.TP 7
+\fB-s\fP
+Force the regeneration of the archive symbol table even if \fIar\fP
+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 \fIstrip\fP. 
+.TP 7
+\fB-t\fP
+Write a table of contents of \fIarchive\fP to the standard output.
+The files specified by the \fIfile\fP operands shall be
+included in the written list. If no \fIfile\fP operands are specified,
+all files in \fIarchive\fP shall be included in the order
+of the archive.
+.TP 7
+\fB-T\fP
+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. 
+.TP 7
+\fB-u\fP
+Update older files in the archive. When used with the \fB-r\fP option,
+files in the archive shall be replaced only if the
+corresponding \fIfile\fP has a modification time that is at least
+as new as the modification time of the file in the archive.
+.TP 7
+\fB-v\fP
+Give verbose output. When used with the option characters \fB-d\fP,
+\fB-r\fP, or \fB-x\fP, write a detailed file-by-file
+description of the archive creation and maintenance activity, as described
+in the STDOUT section. 
+.LP
+When used with \fB-p\fP, 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.
+.LP
+When used with \fB-t\fP, include a long listing of information about
+the files in the archive, as described in the STDOUT
+section.
+.TP 7
+\fB-x\fP
+Extract the files in the archive named by the \fIfile\fP operands
+from \fIarchive\fP. The contents of the archive shall not
+be changed. If no \fIfile\fP 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.
+.sp
+.SH OPERANDS
+.LP
+The following operands shall be supported:
+.TP 7
+\fIarchive\fP
+A pathname of the archive.
+.TP 7
+\fIfile\fP
+A pathname. Only the last component shall be used when comparing against
+the names of files in the archive. If two or more
+\fIfile\fP 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.
+.TP 7
+\fIposname\fP
+The name of a file in the archive, used for relative positioning;
+see options \fB-m\fP and \fB-r\fP. 
+.sp
+.SH STDIN
+.LP
+Not used.
+.SH INPUT FILES
+.LP
+The archive named by \fIarchive\fP shall be a file in the format created
+by \fIar\fP \fB-r\fP.
+.SH ENVIRONMENT VARIABLES
+.LP
+The following environment variables shall affect the execution of
+\fIar\fP:
+.TP 7
+\fILANG\fP
+Provide a default value for the internationalization variables that
+are unset or null. (See the Base Definitions volume of
+IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
+for
+the precedence of internationalization variables used to determine
+the values of locale categories.)
+.TP 7
+\fILC_ALL\fP
+If set to a non-empty string value, override the values of all the
+other internationalization variables.
+.TP 7
+\fILC_CTYPE\fP
+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).
+.TP 7
+\fILC_MESSAGES\fP
+Determine the locale that should be used to affect the format and
+contents of diagnostic messages written to standard
+error.
+.TP 7
+\fILC_TIME\fP
+Determine the format and content for date and time strings written
+by \fIar\fP \fB-tv\fP.
+.TP 7
+\fINLSPATH\fP
+Determine the location of message catalogs for the processing of \fILC_MESSAGES
+\&.\fP 
+.TP 7
+\fITMPDIR\fP
+Determine the pathname that overrides the default directory for temporary
+files, if any.
+.TP 7
+\fITZ\fP
+Determine the timezone used to calculate date and time strings written
+by \fIar\fP \fB-tv\fP. If \fITZ\fP is unset or null,
+an unspecified default timezone shall be used.
+.sp
+.SH ASYNCHRONOUS EVENTS
+.LP
+Default.
+.SH STDOUT
+.LP
+If the \fB-d\fP option is used with the \fB-v\fP option, the standard
+output format shall be:
+.sp
+.RS
+.nf
+
+\fB"d - %s\\n", <\fP\fIfile\fP\fB>
+\fP
+.fi
+.RE
+.LP
+where \fIfile\fP is the operand specified on the command line.
+.LP
+If the \fB-p\fP option is used with the \fB-v\fP option, \fIar\fP
+shall precede the contents of each file with:
+.sp
+.RS
+.nf
+
+\fB"\\n<%s>\\n\\n", <\fP\fIfile\fP\fB>
+\fP
+.fi
+.RE
+.LP
+where \fIfile\fP is the operand specified on the command line, if
+\fIfile\fP operands were specified, and the name of the file
+in the archive if they were not.
+.LP
+If the \fB-r\fP option is used with the \fB-v\fP option:
+.IP " *" 3
+If \fIfile\fP is already in the archive, the standard output format
+shall be:
+.sp
+.RS
+.nf
+
+\fB"r - %s\\n", <\fP\fIfile\fP\fB>
+\fP
+.fi
+.RE
+.LP
+where <\fIfile\fP> is the operand specified on the command line.
+.LP
+.IP " *" 3
+If \fIfile\fP is not already in the archive, the standard output format
+shall be:
+.sp
+.RS
+.nf
+
+\fB"a - %s\\n", <\fP\fIfile\fP\fB>
+\fP
+.fi
+.RE
+.LP
+where <\fIfile\fP> is the operand specified on the command line.
+.LP
+.LP
+If the \fB-t\fP option is used, \fIar\fP shall write the names of
+the files in the archive to the standard output in the
+format:
+.sp
+.RS
+.nf
+
+\fB"%s\\n", <\fP\fIfile\fP\fB>
+\fP
+.fi
+.RE
+.LP
+where \fIfile\fP is the operand specified on the command line, if
+\fIfile\fP operands were specified, or the name of the file
+in the archive if they were not.
+.LP
+If the \fB-t\fP option is used with the \fB-v\fP option, the standard
+output format shall be:
+.sp
+.RS
+.nf
+
+\fB"%s %u/%u %u %s %d %d:%d %d %s\\n", <\fP\fImember mode\fP\fB>, <\fP\fIuser ID\fP\fB>,
+    <\fP\fIgroup ID\fP\fB>, <\fP\fInumber of bytes in member\fP\fB>,
+    <\fP\fIabbreviated month\fP\fB>, <\fP\fIday-of-month\fP\fB>, <\fP\fIhour\fP\fB>,
+    <\fP\fIminute\fP\fB>, <\fP\fIyear\fP\fB>, <\fP\fIfile\fP\fB>
+\fP
+.fi
+.RE
+.LP
+where:
+.TP 7
+<\fIfile\fP>
+Shall be the operand specified on the command line, if \fIfile\fP
+operands were specified, or the name of the file in the
+archive if they were not.
+.TP 7
+<\fImember\ mode\fP>
+.sp
+Shall be formatted the same as the <\fIfile\ mode\fP> string defined
+in the STDOUT section of \fIls\fP, except that the first character,
+the <\fIentry\ type\fP>, 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.
+.sp
+.LP
+The following represent the last-modification time of a file when
+it was most recently added to or replaced in the archive:
+.TP 7
+<\fIabbreviated\ month\fP>
+.sp
+Equivalent to the format of the \fB%b\fP conversion specification
+format in \fIdate\fP.
+.TP 7
+<\fIday-of-month\fP>
+.sp
+Equivalent to the format of the \fB%e\fP conversion specification
+format in \fIdate\fP.
+.TP 7
+<\fIhour\fP>
+Equivalent to the format of the \fB%H\fP conversion specification
+format in \fIdate\fP.
+.TP 7
+<\fIminute\fP>
+Equivalent to the format of the \fB%M\fP conversion specification
+format in \fIdate\fP.
+.TP 7
+<\fIyear\fP>
+Equivalent to the format of the \fB%Y\fP conversion specification
+format in \fIdate\fP.
+.sp
+.LP
+When \fILC_TIME\fP 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.
+.LP
+If the \fB-x\fP option is used with the \fB-v\fP option, the standard
+output format shall be:
+.sp
+.RS
+.nf
+
+\fB"x - %s\\n", <\fP\fIfile\fP\fB>
+\fP
+.fi
+.RE
+.LP
+where \fIfile\fP is the operand specified on the command line, if
+\fIfile\fP operands were specified, or the name of the file
+in the archive if they were not.
+.SH STDERR
+.LP
+The standard error shall be used only for diagnostic messages. The
+diagnostic message about creating a new archive when
+\fB-c\fP is not specified shall not modify the exit status.
+.SH OUTPUT FILES
+.LP
+Archives are files with unspecified formats.
+.SH EXTENDED DESCRIPTION
+.LP
+None.
+.SH EXIT STATUS
+.LP
+The following exit values shall be returned:
+.TP 7
+\ 0
+Successful completion.
+.TP 7
+>0
+An error occurred.
+.sp
+.SH CONSEQUENCES OF ERRORS
+.LP
+Default.
+.LP
+\fIThe following sections are informative.\fP
+.SH APPLICATION USAGE
+.LP
+None.
+.SH EXAMPLES
+.LP
+None.
+.SH RATIONALE
+.LP
+The archive format is not described. It is recognized that there are
+several known \fIar\fP formats, which are not compatible.
+The \fIar\fP 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 \fIar\fP.
+.LP
+Utilities such as \fIpax\fP (and its forebears \fItar\fP and \fIcpio\fP)
+also provide
+portable "archives". This is a not a duplication; the \fIar\fP utility
+is included to provide an interface primarily for \fImake\fP and the
+compilers, based on a historical model.
+.LP
+In historical implementations, the \fB-q\fP option (available on XSI-conforming
+systems) is known to execute quickly because
+\fIar\fP 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.
+.LP
+BSD implementations historically required applications to provide
+the \fB-s\fP option whenever the archive was supposed to
+contain a symbol table. As in this volume of IEEE\ Std\ 1003.1-2001,
+System V historically creates or updates an archive
+symbol table whenever an object file is removed from, added to, or
+updated in the archive.
+.LP
+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 IEEE\ Std\ 1003.1-2001 makes the requirement explicit to avoid
+misunderstandings.
+.LP
+According to the System V documentation, the options \fB-dmpqrtx\fP
+are not required to begin with a hyphen ( \fB'-'\fP ).
+This volume of IEEE\ Std\ 1003.1-2001 requires that a conforming application
+use the leading hyphen.
+.LP
+The archive format used by the 4.4 BSD implementation is documented
+in this RATIONALE as an example:
+A file created by \fIar\fP begins with the "magic" string \fB"!<arch>\\n"\fP
+\&. 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. 
+.LP
+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.
+.LP
+The modification time is the file \fIst_mtime\fP field. The user and
+group IDs are the file \fIst_uid\fP and \fIst_gid\fP
+fields. The file mode is the file \fIst_mode\fP field. The file size
+is the file \fIst_size\fP field. The two-byte trailer is the
+string \fB"`<newline>"\fP .
+.LP
+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 \fB"#1/"\fP 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.
+.LP
+Any unused characters in any of these fields are written as <space>s.
+If any fields are their particular maximum number of
+characters in length, there is no separation between the fields.
+.LP
+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.
+.LP
+The \fIar\fP utility description requires that (when all its members
+are valid object files) \fIar\fP 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, \fIar\fP must provide it; however, \fIar\fP
+does not require a symbol table.
+.LP
+The BSD \fB-o\fP option was omitted. It is a rare conforming application
+that uses \fIar\fP to extract object code from a
+library with concern for its modification time, since this can only
+be of importance to \fImake\fP. Hence, since this functionality is
+not deemed important for applications portability, the
+modification time of the extracted files is set to the current time.
+.LP
+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.
+.LP
+Consideration was given to changing the output format of \fIar\fP
+\fB-tv\fP to the same format as the output of \fIls\fP \fB-l\fP. This
+would have made parsing the output of \fIar\fP the same as that of
+\fIls\fP. This was rejected in part because the current \fIar\fP format
+is commonly used and changes
+would break historical usage. Second, \fIar\fP 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 \fIar\fP cannot know whether the archive was generated
+on the same machine, it cannot tell what to report.
+.LP
+The text on the \fB-ur\fP option combination is historical practice-since
+one filename can easily represent two different files
+(for example, \fB/a/foo\fP and \fB/b/foo\fP), 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
+.LP
+None.
+.SH SEE ALSO
+.LP
+\fIc99\fP, \fIdate\fP, \fIfort77\fP, \fIpax\fP, \fIstrip\fP the
+Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 13, Headers,
+\fI<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, 2003 Edition, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 6, Copyright (C) 2001-2003 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 .