diff options
Diffstat (limited to 'man2/link.2')
| -rw-r--r-- | man2/link.2 | 425 |
1 files changed, 425 insertions, 0 deletions
diff --git a/man2/link.2 b/man2/link.2 new file mode 100644 index 0000000..1533409 --- /dev/null +++ b/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 2023-03-30 "Linux man-pages 6.05.01" +.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> +.PP +.BI "int link(const char *" oldpath ", const char *" newpath ); +.PP +.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" +.B #include <unistd.h> +.PP +.BI "int linkat(int " olddirfd ", const char *" oldpath , +.BI " int " newdirfd ", const char *" newpath ", int " flags ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.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. +.PP +If +.I newpath +exists, it will +.I not +be overwritten. +.PP +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. +.PP +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). +.PP +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 ()). +.PP +If +.I oldpath +is absolute, then +.I olddirfd +is ignored. +.PP +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 . +.PP +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 +.PP +Before Linux 2.6.18, the +.I flags +argument was unused, and had to be specified as 0. +.PP +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.) +.PP +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) |