Merging upstream version 6.8.

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

1 files changed, 265 insertions, 0 deletions

diff --git a/man/man2/symlink.2 b/man/man2/symlink.2
new file mode 100644
index 0000000..ae6e969
--- /dev/null
+++ b/man/man2/symlink.2
@@ -0,0 +1,265 @@
+.\" 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-24 by Rik Faith
+.\" Modified 1996-04-26 by Nick Duffek <nsd@bbc.com>
+.\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
+.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.TH symlink 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+symlink, symlinkat \- 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 symlink(const char *" target ", const char *" linkpath );
+.P
+.BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
+.B #include <unistd.h>
+.P
+.BI "int symlinkat(const char *" target ", int " newdirfd \
+", const char *" linkpath );
+.P
+.fi
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR symlink ():
+.nf
+    _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
+.\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+        || /* glibc <= 2.19: */ _BSD_SOURCE
+.fi
+.P
+.BR symlinkat ():
+.nf
+    Since glibc 2.10:
+        _POSIX_C_SOURCE >= 200809L
+    Before glibc 2.10:
+        _ATFILE_SOURCE
+.fi
+.SH DESCRIPTION
+.BR symlink ()
+creates a symbolic link named
+.I linkpath
+which contains the string
+.IR target .
+.P
+Symbolic links are interpreted at run time as if the contents of the
+link had been substituted into the path being followed to find a file or
+directory.
+.P
+Symbolic links may contain
+.I ..
+path components, which (if used at the start of the link) refer to the
+parent directories of that in which the link resides.
+.P
+A symbolic link (also known as a soft link) may point to an existing
+file or to a nonexistent one; the latter case is known as a dangling
+link.
+.P
+The permissions of a symbolic link are irrelevant; the ownership is
+ignored when following the link
+(except when the
+.I protected_symlinks
+feature is enabled, as explained in
+.BR proc (5)),
+but is checked when removal or
+renaming of the link is requested and the link is in a directory with
+the sticky bit
+.RB ( S_ISVTX )
+set.
+.P
+If
+.I linkpath
+exists, it will
+.I not
+be overwritten.
+.SS symlinkat()
+The
+.BR symlinkat ()
+system call operates in exactly the same way as
+.BR symlink (),
+except for the differences described here.
+.P
+If the pathname given in
+.I linkpath
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.I newdirfd
+(rather than relative to the current working directory of
+the calling process, as is done by
+.BR symlink ()
+for a relative pathname).
+.P
+If
+.I linkpath
+is relative and
+.I newdirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I linkpath
+is interpreted relative to the current working
+directory of the calling process (like
+.BR symlink ()).
+.P
+If
+.I linkpath
+is absolute, then
+.I newdirfd
+is ignored.
+.P
+See
+.BR openat (2)
+for an explanation of the need for
+.BR symlinkat ().
+.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 linkpath
+is denied, or one of the directories in the path prefix of
+.I linkpath
+did not allow search permission.
+(See also
+.BR path_resolution (7).)
+.TP
+.B EBADF
+.RB ( symlinkat ())
+.I linkpath
+is relative but
+.I newdirfd
+is neither
+.B AT_FDCWD
+nor a valid file descriptor.
+.TP
+.B EDQUOT
+The user's quota of resources on the filesystem has been exhausted.
+The resources could be inodes or disk blocks, depending on the filesystem
+implementation.
+.TP
+.B EEXIST
+.I linkpath
+already exists.
+.TP
+.B EFAULT
+.IR target " or " linkpath " 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 linkpath .
+.TP
+.B ENAMETOOLONG
+.IR target " or " linkpath " was too long."
+.TP
+.B ENOENT
+A directory component in
+.I linkpath
+does not exist or is a dangling symbolic link, or
+.I target
+or
+.I linkpath
+is an empty string.
+.TP
+.B ENOENT
+.RB ( symlinkat ())
+.I linkpath
+is a relative pathname and
+.I newdirfd
+refers to a directory that has been deleted.
+.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
+.I linkpath
+is not, in fact, a directory.
+.TP
+.B ENOTDIR
+.RB ( symlinkat ())
+.I linkpath
+is relative and
+.I newdirfd
+is a file descriptor referring to a file other than a directory.
+.TP
+.B EPERM
+The filesystem containing
+.I linkpath
+does not support the creation of symbolic links.
+.TP
+.B EROFS
+.I linkpath
+is on a read-only filesystem.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR symlink ()
+SVr4, 4.3BSD, POSIX.1-2001.
+.\" SVr4 documents additional error codes EDQUOT and ENOSYS.
+.\" See
+.\" .BR open (2)
+.\" re multiple files with the same name, and NFS.
+.TP
+.BR symlinkat ()
+POSIX.1-2008.
+Linux 2.6.16,
+glibc 2.4.
+.SS glibc notes
+On older kernels where
+.BR symlinkat ()
+is unavailable, the glibc wrapper function falls back to the use of
+.BR symlink ().
+When
+.I linkpath
+is a relative pathname,
+glibc constructs a pathname based on the symbolic link in
+.I /proc/self/fd
+that corresponds to the
+.I newdirfd
+argument.
+.SH NOTES
+No checking of
+.I target
+is done.
+.P
+Deleting the name referred to by a symbolic link will actually delete the
+file (unless it also has other hard links).
+If this behavior is not desired, use
+.BR link (2).
+.SH SEE ALSO
+.BR ln (1),
+.BR namei (1),
+.BR lchown (2),
+.BR link (2),
+.BR lstat (2),
+.BR open (2),
+.BR readlink (2),
+.BR rename (2),
+.BR unlink (2),
+.BR path_resolution (7),
+.BR symlink (7)