Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 509 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man1p/cd.1p b/upstream/mageia-cauldron/man1p/cd.1p
new file mode 100644
index 00000000..d73874f5
--- /dev/null
+++ b/upstream/mageia-cauldron/man1p/cd.1p
@@ -0,0 +1,509 @@
+'\" et
+.TH CD "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
+cd
+\(em change the working directory
+.SH SYNOPSIS
+.LP
+.nf
+cd \fB[\fR-L|-P\fB] [\fIdirectory\fB]\fR
+.P
+cd -
+.fi
+.SH DESCRIPTION
+The
+.IR cd
+utility shall change the working directory of the current shell
+execution environment (see
+.IR "Section 2.12" ", " "Shell Execution Environment")
+by executing the following steps in sequence. (In the following steps,
+the symbol
+.BR curpath
+represents an intermediate value used to simplify the description of
+the algorithm used by
+.IR cd .
+There is no requirement that
+.BR curpath
+be made visible to the application.)
+.IP " 1." 4
+If no
+.IR directory
+operand is given and the
+.IR HOME
+environment variable is empty or undefined, the default behavior is
+implementation-defined and no further steps shall be taken.
+.IP " 2." 4
+If no
+.IR directory
+operand is given and the
+.IR HOME
+environment variable is set to a non-empty value, the
+.IR cd
+utility shall behave as if the directory named in the
+.IR HOME
+environment variable was specified as the
+.IR directory
+operand.
+.IP " 3." 4
+If the
+.IR directory
+operand begins with a
+<slash>
+character, set
+.BR curpath
+to the operand and proceed to step 7.
+.IP " 4." 4
+If the first component of the
+.IR directory
+operand is dot or dot-dot, proceed to step 6.
+.IP " 5." 4
+Starting with the first pathname in the
+<colon>-separated
+pathnames of
+.IR CDPATH
+(see the ENVIRONMENT VARIABLES section) if the pathname is non-null,
+test if the concatenation of that pathname, a
+<slash>
+character if that pathname did not end with a
+<slash>
+character, and the
+.IR directory
+operand names a directory. If the pathname is null, test if the
+concatenation of dot, a
+<slash>
+character, and the operand names a directory. In either case, if the
+resulting string names an existing directory, set
+.BR curpath
+to that string and proceed to step 7. Otherwise, repeat this step with
+the next pathname in
+.IR CDPATH
+until all pathnames have been tested.
+.IP " 6." 4
+Set
+.BR curpath
+to the
+.IR directory
+operand.
+.IP " 7." 4
+If the
+.BR \-P
+option is in effect, proceed to step 10. If
+.BR curpath
+does not begin with a
+<slash>
+character, set
+.BR curpath
+to the string formed by the concatenation of the value of
+.IR PWD ,
+a
+<slash>
+character if the value of
+.IR PWD
+did not end with a
+<slash>
+character, and
+.BR curpath .
+.IP " 8." 4
+The
+.BR curpath
+value shall then be converted to canonical form as follows, considering
+each component from beginning to end, in sequence:
+.RS 4 
+.IP " a." 4
+Dot components and any
+<slash>
+characters that separate them from the next component shall be deleted.
+.IP " b." 4
+For each dot-dot component, if there is a preceding component and it is
+neither root nor dot-dot, then:
+.RS 4 
+.IP " i." 5
+If the preceding component does not refer (in the context of pathname
+resolution with symbolic links followed) to a directory, then the
+.IR cd
+utility shall display an appropriate error message and no further steps
+shall be taken.
+.IP ii. 5
+The preceding component, all
+<slash>
+characters separating the preceding component from dot-dot, dot-dot,
+and all
+<slash>
+characters separating dot-dot from the following component (if any)
+shall be deleted.
+.RE
+.IP " c." 4
+An implementation may further simplify
+.BR curpath
+by removing any trailing
+<slash>
+characters that are not also leading
+<slash>
+characters, replacing multiple non-leading consecutive
+<slash>
+characters with a single
+<slash>,
+and replacing three or more leading
+<slash>
+characters with a single
+<slash>.
+If, as a result of this canonicalization, the
+.BR curpath
+variable is null, no further steps shall be taken.
+.RE
+.IP " 9." 4
+If
+.BR curpath
+is longer than
+{PATH_MAX}
+bytes (including the terminating null) and the
+.IR directory
+operand was not longer than
+{PATH_MAX}
+bytes (including the terminating null), then
+.BR curpath
+shall be converted from an absolute pathname to an equivalent relative
+pathname if possible. This conversion shall always be considered
+possible if the value of
+.IR PWD ,
+with a trailing
+<slash>
+added if it does not already have one, is an initial substring of
+.BR curpath .
+Whether or not it is considered possible under other circumstances is
+unspecified. Implementations may also apply this conversion if
+.BR curpath
+is not longer than
+{PATH_MAX}
+bytes or the
+.IR directory
+operand was longer than
+{PATH_MAX}
+bytes.
+.IP 10. 4
+The
+.IR cd
+utility shall then perform actions equivalent to the
+\fIchdir\fR()
+function called with
+.BR curpath
+as the
+.IR path
+argument. If these actions fail for any reason, the
+.IR cd
+utility shall display an appropriate error message and the remainder of
+this step shall not be executed. If the
+.BR \-P
+option is not in effect, the
+.IR PWD
+environment variable shall be set to the value that
+.BR curpath
+had on entry to step 9 (i.e., before conversion to a relative
+pathname). If the
+.BR \-P
+option is in effect, the
+.IR PWD
+environment variable shall be set to the string that would be output by
+.IR pwd
+.BR \-P .
+If there is insufficient permission on the new directory, or on any
+parent of that directory, to determine the current working directory,
+the value of the
+.IR PWD
+environment variable is unspecified.
+.P
+If, during the execution of the above steps, the
+.IR PWD
+environment variable
+is set, the
+.IR OLDPWD
+environment variable shall also be set to
+the value of the old working directory (that is the current working
+directory immediately prior to the call to
+.IR cd ).
+.SH OPTIONS
+The
+.IR cd
+utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Section 12.2" ", " "Utility Syntax Guidelines".
+.P
+The following options shall be supported by the implementation:
+.IP "\fB\-L\fP" 10
+Handle the operand dot-dot logically; symbolic link components shall
+not be resolved before dot-dot components are processed (see steps 8.
+and 9. in the DESCRIPTION).
+.IP "\fB\-P\fP" 10
+Handle the operand dot-dot physically; symbolic link components shall
+be resolved before dot-dot components are processed (see step 7. in the
+DESCRIPTION).
+.P
+If both
+.BR \-L
+and
+.BR \-P
+options are specified, the last of these options shall be used and all
+others ignored. If neither
+.BR \-L
+nor
+.BR \-P
+is specified, the operand shall be handled dot-dot logically; see the
+DESCRIPTION.
+.SH OPERANDS
+The following operands shall be supported:
+.IP "\fIdirectory\fR" 10
+An absolute or relative pathname of the directory that shall become
+the new working directory. The interpretation of a relative pathname
+by
+.IR cd
+depends on the
+.BR \-L
+option and the
+.IR CDPATH
+and
+.IR PWD
+environment variables. If
+.IR directory
+is an empty string, the results are unspecified.
+.IP "\-" 10
+When a
+<hyphen-minus>
+is used as the operand, this shall be equivalent to the command:
+.RS 10 
+.sp
+.RS 4
+.nf
+
+cd "$OLDPWD" && pwd
+.fi
+.P
+.RE
+.P
+which changes to the previous working directory and then writes its
+name.
+.RE
+.SH STDIN
+Not used.
+.SH "INPUT FILES"
+None.
+.SH "ENVIRONMENT VARIABLES"
+The following environment variables shall affect the execution of
+.IR cd :
+.IP "\fICDPATH\fP" 10
+A
+<colon>-separated
+list of pathnames that refer to directories. The
+.IR cd
+utility shall use this list in its attempt to change the directory, as
+described in the DESCRIPTION. An empty string in place of a directory
+pathname represents the current directory. If
+.IR CDPATH
+is not set, it shall be treated as if it were an empty string.
+.IP "\fIHOME\fP" 10
+The name of the directory, used when no
+.IR directory
+operand is specified.
+.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).
+.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 "\fINLSPATH\fP" 10
+Determine the location of message catalogs for the processing of
+.IR LC_MESSAGES .
+.IP "\fIOLDPWD\fP" 10
+A pathname of the previous working directory, used by
+.IR cd
+.BR \- .
+.IP "\fIPWD\fP" 10
+This variable shall be set as specified in the DESCRIPTION. If an
+application sets or unsets the value of
+.IR PWD ,
+the behavior of
+.IR cd
+is unspecified.
+.SH "ASYNCHRONOUS EVENTS"
+Default.
+.SH STDOUT
+If a non-empty directory name from
+.IR CDPATH
+is used, or if
+.IR cd
+.BR \-
+is used, an absolute pathname of the new working directory shall be
+written to the standard output as follows:
+.sp
+.RS 4
+.nf
+
+"%s\en", <\fInew directory\fR>
+.fi
+.P
+.RE
+.P
+Otherwise, there shall be no output.
+.SH STDERR
+The standard error shall be used only for diagnostic messages.
+.SH "OUTPUT FILES"
+None.
+.SH "EXTENDED DESCRIPTION"
+None.
+.SH "EXIT STATUS"
+The following exit values shall be returned:
+.IP "\00" 6
+The directory was successfully changed.
+.IP >0 6
+An error occurred.
+.SH "CONSEQUENCES OF ERRORS"
+The working directory shall remain unchanged.
+.LP
+.IR "The following sections are informative."
+.SH "APPLICATION USAGE"
+Since
+.IR cd
+affects the current shell execution environment, it is always provided
+as a shell regular built-in. If it is called in a subshell or separate
+utility execution environment, such as one of the following:
+.sp
+.RS 4
+.nf
+
+(cd /tmp)
+nohup cd
+find . -exec cd {} \e;
+.fi
+.P
+.RE
+.P
+it does not affect the working directory of the caller's environment.
+.P
+The user must have execute (search) permission in
+.IR directory
+in order to change to it.
+.SH EXAMPLES
+The following template can be used to perform processing in the directory
+specified by
+.IR location
+and end up in the current working directory in use before the first
+.IR cd
+command was issued:
+.sp
+.RS 4
+.nf
+
+cd \fIlocation\fP
+if [ $? -ne 0 ]
+then
+    print error message
+    exit 1
+fi
+\&... do whatever is desired as long as the OLDPWD environment variable
+    is not modified
+cd -
+.fi
+.P
+.RE
+.SH RATIONALE
+The use of the
+.IR CDPATH
+was introduced in the System V shell. Its use is analogous to the use
+of the
+.IR PATH
+variable in the shell. The BSD C shell used a shell parameter
+.IR cdpath
+for this purpose.
+.P
+A common extension when
+.IR HOME
+is undefined is to get the login directory from the user database for
+the invoking user. This does not occur on System V implementations.
+.P
+Some historical shells, such as the KornShell, took special actions
+when the directory name contained a dot-dot component, selecting the
+logical parent of the directory, rather than the actual parent
+directory; that is, it moved up one level toward the
+.BR '/' 
+in the pathname, remembering what the user typed, rather than
+performing the equivalent of:
+.sp
+.RS 4
+.nf
+
+chdir("..");
+.fi
+.P
+.RE
+.P
+In such a shell, the following commands would not necessarily produce
+equivalent output for all directories:
+.sp
+.RS 4
+.nf
+
+cd .. && ls      ls ..
+.fi
+.P
+.RE
+.P
+This behavior is now the default. It is not consistent with the
+definition of dot-dot in most historical practice; that is, while this
+behavior has been optionally available in the KornShell, other shells
+have historically not supported this functionality. The logical
+pathname is stored in the
+.IR PWD
+environment variable when the
+.IR cd
+utility completes and this value is used to construct the next
+directory name if
+.IR cd
+is invoked with the
+.BR \-L
+option.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "Section 2.12" ", " "Shell Execution Environment",
+.IR "\fIpwd\fR\^"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "Chapter 8" ", " "Environment Variables",
+.IR "Section 12.2" ", " "Utility Syntax Guidelines"
+.P
+The System Interfaces volume of POSIX.1\(hy2017,
+.IR "\fIchdir\fR\^(\|)"
+.\"
+.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 .