Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 729 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1p/ar.1p b/upstream/mageia-cauldron/man1p/ar.1p
new file mode 100644
index 00000000..4b41b7cd
--- /dev/null
+++ b/upstream/mageia-cauldron/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 .