From a469d976ed62a8364f0b48abf17d8acc186f2a3d Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Fri, 21 Feb 2014 09:57:06 +0100 Subject: [PATCH] link.2: Merge text of linkat(2) Signed-off-by: Michael Kerrisk --- man2/link.2 | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 175 insertions(+), 3 deletions(-) diff --git a/man2/link.2 b/man2/link.2 index 8861e8874..4553cbd7c 100644 --- a/man2/link.2 +++ b/man2/link.2 @@ -1,5 +1,6 @@ .\" This manpage is Copyright (C) 1992 Drew Eckhardt; .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2006, 2014 Michael Kerrisk .\" .\" %%%LICENSE_START(VERBATIM) .\" Permission is granted to make and distribute verbatim copies of this @@ -28,13 +29,40 @@ .\" Modified 2004-06-23 by Michael Kerrisk .\" Modified 2005-04-04, as per suggestion by Michael Hardt for rename.2 .\" -.TH LINK 2 2013-01-27 "Linux" "Linux Programmer's Manual" +.TH LINK 2 2014-02-21 "Linux" "Linux Programmer's Manual" .SH NAME -link \- make a new name for a file +link, linkat \- make a new name for a file .SH SYNOPSIS +.nf .B #include .sp .BI "int link(const char *" oldpath ", const char *" newpath ); +.sp +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.sp +.BI "int linkat(int " olddirfd ", const char *" oldpath , +.BI " int " newdirfd ", const char *" newpath ", int " flags ); +.fi +.sp +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.sp +.BR linkat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE +.ad +.PD .SH DESCRIPTION .BR link () creates a new link (also known as a hard link) to an existing file. @@ -49,6 +77,102 @@ 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 (2), +except for the differences described here. + +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 (2) +for a relative pathname). + +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 (2)). + +If +.I oldpath +is absolute, then +.I olddirfd +is ignored. + +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 . + +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 +.IR 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, not just a directory. +The caller must have the +.BR CAP_DAC_READ_SEARCH +capability in order to use this flag; +this prevents arbitrary users from creating hard links +using file descriptors received via a UNIX domain socket +(see the discussion of +.BR SCM_RIGHTS +in +.BR unix (7)). +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 (2)). +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. +.PP +Before kernel 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 @@ -135,11 +259,60 @@ are not on the same mounted filesystem. .BR link () does not work across different mount points, even if the same filesystem is mounted on both.) +.PP +The following additional errors can occur for +.BR linkat (): +.TP +.B EBADF +.I olddirfd +or +.I newdirfd +is not 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 + + open(path, O_TMPFILE | O_EXCL, mode); + +See +.BR open (2). +.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 +.SH VERSIONS +.BR linkat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. .SH CONFORMING TO +.BR link (): SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES). .\" SVr4 documents additional ENOLINK and .\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP. .\" X/OPEN does not document EFAULT, ENOMEM or EIO. + +.BR linkat (): +POSIX.1-2008. .SH NOTES Hard links, as created by .BR link (), @@ -186,7 +359,6 @@ Use to find out if the link got created. .SH SEE ALSO .BR ln (1), -.BR linkat (2), .BR open (2), .BR rename (2), .BR stat (2),