diff options
Diffstat (limited to 'man/man2/symlink.2')
| -rw-r--r-- | man/man2/symlink.2 | 265 |
1 files changed, 265 insertions, 0 deletions
diff --git a/man/man2/symlink.2 b/man/man2/symlink.2 new file mode 100644 index 000000000..21ab4fa45 --- /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 (date) "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) |