Merging upstream version 6.8.

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

1 files changed, 425 insertions, 0 deletions

diff --git a/man/man2/link.2 b/man/man2/link.2
new file mode 100644
index 0000000..9f09b0b
--- /dev/null
+++ b/man/man2/link.2
@@ -0,0 +1,425 @@
+.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
+.\"             and Copyright (C) 1993 Michael Haardt, Ian Jackson.
+.\" and Copyright (C) 2006, 2014 Michael Kerrisk
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
+.\" Modified 1994-08-21 by Michael Haardt
+.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Modified 2005-04-04, as per suggestion by Michael Hardt for rename.2
+.\"
+.TH link 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+link, linkat \- make a new name for a file
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.BI "int link(const char *" oldpath ", const char *" newpath );
+.P
+.BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int linkat(int " olddirfd ", const char *" oldpath ,
+.BI "           int " newdirfd ", const char *" newpath ", int " flags );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR linkat ():
+.nf
+    Since glibc 2.10:
+        _POSIX_C_SOURCE >= 200809L
+    Before glibc 2.10:
+        _ATFILE_SOURCE
+.fi
+.SH DESCRIPTION
+.BR link ()
+creates a new link (also known as a hard link) to an existing file.
+.P
+If
+.I newpath
+exists, it will
+.I not
+be overwritten.
+.P
+This new name may be used exactly as the old one for any operation;
+both names refer to the same file (and so have the same permissions
+and ownership) and it is impossible to tell which name was the
+"original".
+.SS linkat()
+The
+.BR linkat ()
+system call operates in exactly the same way as
+.BR link (),
+except for the differences described here.
+.P
+If the pathname given in
+.I oldpath
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I olddirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR link ()
+for a relative pathname).
+.P
+If
+.I oldpath
+is relative and
+.I olddirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I oldpath
+is interpreted relative to the current working
+directory of the calling process (like
+.BR link ()).
+.P
+If
+.I oldpath
+is absolute, then
+.I olddirfd
+is ignored.
+.P
+The interpretation of
+.I newpath
+is as for
+.IR oldpath ,
+except that a relative pathname is interpreted relative
+to the directory referred to by the file descriptor
+.IR newdirfd .
+.P
+The following values can be bitwise ORed in
+.IR flags :
+.TP
+.BR AT_EMPTY_PATH " (since Linux 2.6.39)"
+.\" commit 11a7b371b64ef39fc5fb1b6f2218eef7c4d035e3
+If
+.I oldpath
+is an empty string, create a link to the file referenced by
+.I olddirfd
+(which may have been obtained using the
+.BR open (2)
+.B O_PATH
+flag).
+In this case,
+.I olddirfd
+can refer to any type of file except a directory.
+This will generally not work if the file has a link count of zero (files
+created with
+.B O_TMPFILE
+and without
+.B O_EXCL
+are an exception).
+The caller must have the
+.B CAP_DAC_READ_SEARCH
+capability in order to use this flag.
+This flag is Linux-specific; define
+.B _GNU_SOURCE
+.\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
+to obtain its definition.
+.TP
+.BR AT_SYMLINK_FOLLOW " (since Linux 2.6.18)"
+By default,
+.BR linkat (),
+does not dereference
+.I oldpath
+if it is a symbolic link (like
+.BR link ()).
+The flag
+.B AT_SYMLINK_FOLLOW
+can be specified in
+.I flags
+to cause
+.I oldpath
+to be dereferenced if it is a symbolic link.
+If procfs is mounted,
+this can be used as an alternative to
+.BR AT_EMPTY_PATH ,
+like this:
+.IP
+.in +4n
+.EX
+linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd,
+       newname, AT_SYMLINK_FOLLOW);
+.EE
+.in
+.P
+Before Linux 2.6.18, the
+.I flags
+argument was unused, and had to be specified as 0.
+.P
+See
+.BR openat (2)
+for an explanation of the need for
+.BR linkat ().
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+Write access to the directory containing
+.I newpath
+is denied, or search permission is denied for one of the directories
+in the path prefix of
+.I oldpath
+or
+.IR newpath .
+(See also
+.BR path_resolution (7).)
+.TP
+.B EDQUOT
+The user's quota of disk blocks on the filesystem has been exhausted.
+.TP
+.B EEXIST
+.I newpath
+already exists.
+.TP
+.B EFAULT
+.IR oldpath " or " newpath " points outside your accessible address space."
+.TP
+.B EIO
+An I/O error occurred.
+.TP
+.B ELOOP
+Too many symbolic links were encountered in resolving
+.IR oldpath " or " newpath .
+.TP
+.B EMLINK
+The file referred to by
+.I oldpath
+already has the maximum number of links to it.
+For example, on an
+.BR ext4 (5)
+filesystem that does not employ the
+.I dir_index
+feature, the limit on the number of hard links to a file is 65,000; on
+.BR btrfs (5),
+the limit is 65,535 links.
+.TP
+.B ENAMETOOLONG
+.IR oldpath " or " newpath " was too long."
+.TP
+.B ENOENT
+A directory component in
+.IR oldpath " or " newpath
+does not exist or is a dangling symbolic link.
+.TP
+.B ENOMEM
+Insufficient kernel memory was available.
+.TP
+.B ENOSPC
+The device containing the file has no room for the new directory
+entry.
+.TP
+.B ENOTDIR
+A component used as a directory in
+.IR oldpath " or " newpath
+is not, in fact, a directory.
+.TP
+.B EPERM
+.I oldpath
+is a directory.
+.TP
+.B EPERM
+The filesystem containing
+.IR oldpath " and " newpath
+does not support the creation of hard links.
+.TP
+.BR EPERM " (since Linux 3.6)"
+The caller does not have permission to create a hard link to this file
+(see the description of
+.I /proc/sys/fs/protected_hardlinks
+in
+.BR proc (5)).
+.TP
+.B EPERM
+.I oldpath
+is marked immutable or append-only.
+(See
+.BR ioctl_iflags (2).)
+.TP
+.B EROFS
+The file is on a read-only filesystem.
+.TP
+.B EXDEV
+.IR oldpath " and " newpath
+are not on the same mounted filesystem.
+(Linux permits a filesystem to be mounted at multiple points, but
+.BR link ()
+does not work across different mounts,
+even if the same filesystem is mounted on both.)
+.P
+The following additional errors can occur for
+.BR linkat ():
+.TP
+.B EBADF
+.I oldpath
+.RI ( newpath )
+is relative but
+.I olddirfd
+.RI ( newdirfd )
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
+.TP
+.B EINVAL
+An invalid flag value was specified in
+.IR flags .
+.TP
+.B ENOENT
+.B AT_EMPTY_PATH
+was specified in
+.IR flags ,
+but the caller did not have the
+.B CAP_DAC_READ_SEARCH
+capability.
+.TP
+.B ENOENT
+An attempt was made to link to the
+.I /proc/self/fd/NN
+file corresponding to a file descriptor created with
+.IP
+.in +4n
+.EX
+open(path, O_TMPFILE | O_EXCL, mode);
+.EE
+.in
+.IP
+See
+.BR open (2).
+.TP
+.B ENOENT
+An attempt was made to link to a
+.I /proc/self/fd/NN
+file corresponding to a file that has been deleted.
+.TP
+.B ENOENT
+.I oldpath
+is a relative pathname and
+.I olddirfd
+refers to a directory that has been deleted,
+or
+.I newpath
+is a relative pathname and
+.I newdirfd
+refers to a directory that has been deleted.
+.TP
+.B ENOTDIR
+.I oldpath
+is relative and
+.I olddirfd
+is a file descriptor referring to a file other than a directory;
+or similar for
+.I newpath
+and
+.I newdirfd
+.TP
+.B EPERM
+.B AT_EMPTY_PATH
+was specified in
+.IR flags ,
+.I oldpath
+is an empty string, and
+.I olddirfd
+refers to a directory.
+.SH VERSIONS
+POSIX.1-2001 says that
+.BR link ()
+should dereference
+.I oldpath
+if it is a symbolic link.
+However, since Linux 2.0,
+.\" more precisely: since Linux 1.3.56
+Linux does not do so: if
+.I oldpath
+is a symbolic link, then
+.I newpath
+is created as a (hard) link to the same symbolic link file
+(i.e.,
+.I newpath
+becomes a symbolic link to the same file that
+.I oldpath
+refers to).
+Some other implementations behave in the same manner as Linux.
+.\" For example, the default Solaris compilation environment
+.\" behaves like Linux, and contributors to a March 2005
+.\" thread in the Austin mailing list reported that some
+.\" other (System V) implementations did/do the same -- MTK, Apr 05
+POSIX.1-2008 changes the specification of
+.BR link (),
+making it implementation-dependent whether or not
+.I oldpath
+is dereferenced if it is a symbolic link.
+For precise control over the treatment of symbolic links when
+creating a link, use
+.BR linkat ().
+.SS glibc
+On older kernels where
+.BR linkat ()
+is unavailable, the glibc wrapper function falls back to the use of
+.BR link (),
+unless the
+.B AT_SYMLINK_FOLLOW
+is specified.
+When
+.I oldpath
+and
+.I newpath
+are relative pathnames,
+glibc constructs pathnames based on the symbolic links in
+.I /proc/self/fd
+that correspond to the
+.I olddirfd
+and
+.I newdirfd
+arguments.
+.SH STANDARDS
+.TP
+.BR link ()
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR link ()
+SVr4, 4.3BSD, POSIX.1-2001 (but see VERSIONS).
+.\" SVr4 documents additional ENOLINK and
+.\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP.
+.\" X/OPEN does not document EFAULT, ENOMEM or EIO.
+.TP
+.BR linkat ()
+POSIX.1-2008.
+Linux 2.6.16,
+glibc 2.4.
+.SH NOTES
+Hard links, as created by
+.BR link (),
+cannot span filesystems.
+Use
+.BR symlink (2)
+if this is required.
+.SH BUGS
+On NFS filesystems, the return code may be wrong in case the NFS server
+performs the link creation and dies before it can say so.
+Use
+.BR stat (2)
+to find out if the link got created.
+.SH SEE ALSO
+.BR ln (1),
+.BR open (2),
+.BR rename (2),
+.BR stat (2),
+.BR symlink (2),
+.BR unlink (2),
+.BR path_resolution (7),
+.BR symlink (7)