1 files changed, 470 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/link.3p b/upstream/archlinux/man3p/link.3p
new file mode 100644
index 00000000..846a6fca
--- /dev/null
+++ b/upstream/archlinux/man3p/link.3p
@@ -0,0 +1,470 @@
+'\" et
+.TH LINK "3P" 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
+link, linkat
+\(em link one file to another file
+.SH SYNOPSIS
+.LP
+.nf
+#include <unistd.h>
+.P
+int link(const char *\fIpath1\fP, const char *\fIpath2\fP);
+.P
+#include <fcntl.h>
+.P
+int linkat(int \fIfd1\fP, const char *\fIpath1\fP, int \fIfd2\fP,
+    const char *\fIpath2\fP, int \fIflag\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIlink\fR()
+function shall create a new link (directory entry) for the existing file,
+.IR path1 .
+.P
+The
+.IR path1
+argument points to a pathname naming an existing file. The
+.IR path2
+argument points to a pathname naming the new directory entry to be
+created. The
+\fIlink\fR()
+function shall atomically create a new link for the existing file and
+the link count of the file shall be incremented by one.
+.P
+If
+.IR path1
+names a directory,
+\fIlink\fR()
+shall fail unless the process has appropriate privileges and the
+implementation supports using
+\fIlink\fR()
+on directories.
+.P
+If
+.IR path1
+names a symbolic link, it is implementation-defined whether
+\fIlink\fR()
+follows the symbolic link, or creates a new link to the symbolic
+link itself.
+.P
+Upon successful completion,
+\fIlink\fR()
+shall mark for update the last file status change timestamp of the
+file. Also, the last data modification and last file status change
+timestamps of the directory that contains the new entry shall be marked
+for update.
+.P
+If
+\fIlink\fR()
+fails, no link shall be created and the link count of the file shall
+remain unchanged.
+.P
+The implementation may require that the calling process has permission
+to access the existing file.
+.P
+The
+\fIlinkat\fR()
+function shall be equivalent to the
+\fIlink\fR()
+function except that symbolic links shall be handled as specified by
+the value of
+.IR flag
+(see below) and except in the case where either
+.IR path1
+or
+.IR path2
+or both are relative paths. In this case a relative path
+.IR path1
+is interpreted relative to the directory associated with the file
+descriptor
+.IR fd1
+instead of the current working directory and similarly for
+.IR path2
+and the file descriptor
+.IR fd2 .
+If the access mode of the open file description associated with the
+file descriptor is not O_SEARCH, the function shall check whether
+directory searches are permitted using the current permissions of
+the directory underlying the file descriptor. If the access mode is
+O_SEARCH, the function shall not perform the check.
+.P
+Values for
+.IR flag
+are constructed by a bitwise-inclusive OR of flags from the following
+list, defined in
+.IR <fcntl.h> :
+.IP AT_SYMLINK_FOLLOW 6
+.br
+If
+.IR path1
+names a symbolic link, a new link for the target of the symbolic link
+is created.
+.P
+If
+\fIlinkat\fR()
+is passed the special value AT_FDCWD in the
+.IR fd1
+or
+.IR fd2
+parameter, the current working directory shall be used for the respective
+.IR path
+argument. If both
+.IR fd1
+and
+.IR fd2
+have value AT_FDCWD, the behavior shall be identical to a call to
+\fIlink\fR(),
+except that symbolic links shall be handled as specified by the value of
+.IR flag .
+.P
+If the AT_SYMLINK_FOLLOW flag is clear in the
+.IR flag
+argument and the
+.IR path1
+argument names a symbolic link, a new link is created for the symbolic
+link
+.IR path1
+and not its target.
+.SH "RETURN VALUE"
+Upon successful completion, these functions shall return 0. Otherwise,
+these functions shall return \-1 and set
+.IR errno
+to indicate the error.
+.br
+.SH ERRORS
+These functions shall fail if:
+.TP
+.BR EACCES
+A component of either path prefix denies search permission, or the
+requested link requires writing in a directory that denies write
+permission, or the calling process does not have permission to access
+the existing file and this is required by the implementation.
+.TP
+.BR EEXIST
+The
+.IR path2
+argument resolves to an existing directory entry or refers to a symbolic
+link.
+.TP
+.BR ELOOP
+A loop exists in symbolic links encountered during resolution of the
+.IR path1
+or
+.IR path2
+argument.
+.TP
+.BR EMLINK
+The number of links to the file named by
+.IR path1
+would exceed
+{LINK_MAX}.
+.TP
+.BR ENAMETOOLONG
+.br
+The length of a component of a pathname is longer than
+{NAME_MAX}.
+.TP
+.BR ENOENT
+A component of either path prefix does not exist; the file named by
+.IR path1
+does not exist; or
+.IR path1
+or
+.IR path2
+points to an empty string.
+.TP
+.BR ENOENT " or " ENOTDIR
+.br
+The
+.IR path1
+argument names an existing non-directory file, and the
+.IR path2
+argument contains at least one non-\c
+<slash>
+character and ends with one or more trailing
+<slash>
+characters. If
+.IR path2
+without the trailing
+<slash>
+characters would name an existing file, an
+.BR [ENOENT] 
+error shall not occur.
+.TP
+.BR ENOSPC
+The directory to contain the link cannot be extended.
+.TP
+.BR ENOTDIR
+A component of either path prefix names an existing file that is neither
+a directory nor a symbolic link to a directory, or the
+.IR path1
+argument contains at least one non-\c
+<slash>
+character and ends with one or more trailing
+<slash>
+characters and the last pathname component names an existing file
+that is neither a directory nor a symbolic link to a directory, or the
+.IR path1
+argument names an existing non-directory file and the
+.IR path2
+argument names a nonexistent file, contains at least one non-\c
+<slash>
+character, and ends with one or more trailing
+<slash>
+characters.
+.TP
+.BR EPERM
+The file named by
+.IR path1
+is a directory and either the calling process does not have appropriate
+privileges or the implementation prohibits using
+\fIlink\fR()
+on directories.
+.TP
+.BR EROFS
+The requested link requires writing in a directory on a read-only file
+system.
+.TP
+.BR EXDEV
+The link named by
+.IR path2
+and the file named by
+.IR path1
+are on different file systems and the implementation does not support
+links between file systems.
+.TP
+.BR EXDEV
+.IR path1
+refers to a named STREAM.
+.P
+The
+\fIlinkat\fR()
+function shall fail if:
+.TP
+.BR EACCES
+The access mode of the open file description associated with
+.IR fd1
+or
+.IR fd2
+is not O_SEARCH and the permissions of the directory underlying
+.IR fd1
+or
+.IR fd2 ,
+respectively, do not permit directory searches.
+.TP
+.BR EBADF
+The
+.IR path1
+or
+.IR path2
+argument does not specify an absolute path and the
+.IR fd1
+or
+.IR fd2
+argument, respectively, is neither AT_FDCWD nor a valid file descriptor
+open for reading or searching.
+.TP
+.BR ENOTDIR
+The
+.IR path1
+or
+.IR path2
+argument is not an absolute path and
+.IR fd1
+or
+.IR fd2 ,
+respectively, is a file descriptor associated with a non-directory file.
+.P
+These functions may fail if:
+.TP
+.BR ELOOP
+More than
+{SYMLOOP_MAX}
+symbolic links were encountered during resolution of the
+.IR path1
+or
+.IR path2
+argument.
+.TP
+.BR ENAMETOOLONG
+.br
+The length of a pathname exceeds
+{PATH_MAX},
+or pathname resolution of a symbolic link produced an intermediate
+result with a length that exceeds
+{PATH_MAX}.
+.br
+.P
+The
+\fIlinkat\fR()
+function may fail if:
+.TP
+.BR EINVAL
+The value of the
+.IR flag
+argument is not valid.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+.SS "Creating a Link to a File"
+.P
+The following example shows how to create a link to a file named
+.BR /home/cnd/mod1
+by creating a new directory entry named
+.BR /modules/pass1 .
+.sp
+.RS 4
+.nf
+
+#include <unistd.h>
+.P
+char *path1 = "/home/cnd/mod1";
+char *path2 = "/modules/pass1";
+int   status;
+\&...
+status = link (path1, path2);
+.fi
+.P
+.RE
+.SS "Creating a Link to a File Within a Program"
+.P
+In the following program example, the
+\fIlink\fR()
+function links the
+.BR /etc/passwd
+file (defined as
+.BR PASSWDFILE )
+to a file named
+.BR /etc/opasswd
+(defined as
+.BR SAVEFILE ),
+which is used to save the current password file. Then, after removing
+the current password file (defined as
+.BR PASSWDFILE ),
+the new password file is saved as the current password file using the
+\fIlink\fR()
+function again.
+.sp
+.RS 4
+.nf
+
+#include <unistd.h>
+.P
+#define LOCKFILE "/etc/ptmp"
+#define PASSWDFILE "/etc/passwd"
+#define SAVEFILE "/etc/opasswd"
+\&...
+/* Save current password file */
+link (PASSWDFILE, SAVEFILE);
+.P
+/* Remove current password file. */
+unlink (PASSWDFILE);
+.P
+/* Save new password file as current password file. */
+link (LOCKFILE,PASSWDFILE);
+.fi
+.P
+.RE
+.SH "APPLICATION USAGE"
+Some implementations do allow links between file systems.
+.P
+If
+.IR path1
+refers to a symbolic link, application developers should use
+\fIlinkat\fR()
+with appropriate flags to select whether or not the symbolic link should
+be resolved.
+.SH RATIONALE
+Linking to a directory is restricted to the superuser
+in most historical implementations because this capability may produce
+loops in the file hierarchy or otherwise corrupt the file system. This volume of POSIX.1\(hy2017
+continues that philosophy by prohibiting
+\fIlink\fR()
+and
+\fIunlink\fR()
+from doing this. Other functions could do it if the implementor designed
+such an extension.
+.P
+Some historical implementations allow linking of files on different file
+systems. Wording was added to explicitly allow this optional behavior.
+.P
+The exception for cross-file system links is intended to apply only to
+links that are programmatically indistinguishable from ``hard'' links.
+.P
+The purpose of the
+\fIlinkat\fR()
+function is to link files in directories other than the current working
+directory without exposure to race conditions. Any part of the path of
+a file could be changed in parallel to a call to
+\fIlink\fR(),
+resulting in unspecified behavior. By opening a file descriptor for the
+directory of both the existing file and the target location and using the
+\fIlinkat\fR()
+function it can be guaranteed that the both filenames are in the desired
+directories.
+.P
+The AT_SYMLINK_FOLLOW flag allows for implementing both common behaviors
+of the
+\fIlink\fR()
+function. The POSIX specification requires that if
+.IR path1
+is a symbolic link, a new link for the target of the symbolic link is
+created. Many systems by default or as an alternative provide a mechanism
+to avoid the implicit symbolic link lookup and create a new link for
+the symbolic link itself.
+.P
+Earlier versions of this standard specified only the
+\fIlink\fR()
+function, and required it to behave like
+\fIlinkat\fR()
+with the AT_SYMLINK_FOLLOW flag. However, historical practice from SVR4
+and Linux kernels had
+\fIlink\fR()
+behaving like
+\fIlinkat\fR()
+with no flags, and many systems that attempted to provide a conforming
+\fIlink\fR()
+function did so in a way that was rarely used, and when it was used
+did not conform to the standard (e.g., by not being atomic, or by
+dereferencing the symbolic link incorrectly). Since applications could
+not rely on
+\fIlink\fR()
+following links in practice, the
+\fIlinkat\fR()
+function was added taking a flag to specify the desired behavior
+for the application.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIrename\fR\^(\|)",
+.IR "\fIsymlink\fR\^(\|)",
+.IR "\fIunlink\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<fcntl.h>\fP",
+.IR "\fB<unistd.h>\fP"
+.\"
+.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 .