original/man2/linkat.2

   1 .\" This manpage is Copyright (C) 2006, Michael Kerrisk
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH LINKAT 2 2013-07-21 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 linkat \- create a file link relative to directory file descriptors
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <fcntl.h>           /* Definition of AT_* constants */
  31 .B #include <unistd.h>
  32 .sp
  33 .BI "int linkat(int " olddirfd ", const char *" oldpath ,
  34 .BI "           int " newdirfd ", const char *" newpath ", int " flags );
  35 .fi
  36 .sp
  37 .in -4n
  38 Feature Test Macro Requirements for glibc (see
  39 .BR feature_test_macros (7)):
  40 .in
  41 .sp
  42 .BR linkat ():
  43 .PD 0
  44 .ad l
  45 .RS 4
  46 .TP 4
  47 Since glibc 2.10:
  48 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  49 .TP
  50 Before glibc 2.10:
  51 _ATFILE_SOURCE
  52 .RE
  53 .ad
  54 .PD
  55 .SH DESCRIPTION
  56 The
  57 .BR linkat ()
  58 system call operates in exactly the same way as
  59 .BR link (2),
  60 except for the differences described in this manual page.
  61
  62 If the pathname given in
  63 .I oldpath
  64 is relative, then it is interpreted relative to the directory
  65 referred to by the file descriptor
  66 .I olddirfd
  67 (rather than relative to the current working directory of
  68 the calling process, as is done by
  69 .BR link (2)
  70 for a relative pathname).
  71
  72 If
  73 .I oldpath
  74 is relative and
  75 .I olddirfd
  76 is the special value
  77 .BR AT_FDCWD ,
  78 then
  79 .I oldpath
  80 is interpreted relative to the current working
  81 directory of the calling process (like
  82 .BR link (2)).
  83
  84 If
  85 .I oldpath
  86 is absolute, then
  87 .I olddirfd
  88 is ignored.
  89
  90 The interpretation of
  91 .I newpath
  92 is as for
  93 .IR oldpath ,
  94 except that a relative pathname is interpreted relative
  95 to the directory referred to by the file descriptor
  96 .IR newdirfd .
  97
  98 The following values can be biwise ORed in
  99 .IR flags :
 100 .TP
 101 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
 102 .\" commit 11a7b371b64ef39fc5fb1b6f2218eef7c4d035e3
 103 If
 104 .I oldpath
 105 is an empty string, create a link to the file referenced by
 106 .IR olddirfd
 107 (which may have been obtained using the
 108 .BR open (2)
 109 .B O_PATH
 110 flag).
 111 In this case,
 112 .I olddirfd
 113 can refer to any type of file, not just a directory.
 114 The caller must have the
 115 .BR CAP_DAC_READ_SEARCH
 116 capability in order to use this flag;
 117 this prevents arbitrary users from creating hard links
 118 using file descriptors received via a UNIX domain socket
 119 (see the discussion of
 120 .BR SCM_RIGHTS
 121 in
 122 .BR unix (7)).
 123 .TP
 124 .BR AT_SYMLINK_FOLLOW " (since Linux 2.6.18)"
 125 By default,
 126 .BR linkat (),
 127 does not dereference
 128 .I oldpath
 129 if it is a symbolic link (like
 130 .BR link (2)).
 131 The flag
 132 .B AT_SYMLINK_FOLLOW
 133 can be specified in
 134 .I flags
 135 to cause
 136 .I oldpath
 137 to be dereferenced if it is a symbolic link.
 138 .PP
 139 Before kernel 2.6.18, the
 140 .I flags
 141 argument was unused, and had to be specified as 0.
 142 .SH RETURN VALUE
 143 On success,
 144 .BR linkat ()
 145 returns 0.
 146 On error, \-1 is returned and
 147 .I errno
 148 is set to indicate the error.
 149 .SH ERRORS
 150 The same errors that occur for
 151 .BR link (2)
 152 can also occur for
 153 .BR linkat ().
 154 The following additional errors can occur for
 155 .BR linkat ():
 156 .TP
 157 .B EBADF
 158 .I olddirfd
 159 or
 160 .I newdirfd
 161 is not a valid file descriptor.
 162 .TP
 163 .B ENOENT
 164 .B AT_EMPTY_PATH
 165 was specified in
 166 .IR flags ,
 167 but the caller did not have the
 168 .B CAP_DAC_READ_SEARCH
 169 capability.
 170 .TP
 171 .B ENOTDIR
 172 .TP
 173 .B ENOTDIR
 174 .I oldpath
 175 is relative and
 176 .I olddirfd
 177 is a file descriptor referring to a file other than a directory;
 178 or similar for
 179 .I newpath
 180 and
 181 .I newdirfd
 182 .SH VERSIONS
 183 .BR linkat ()
 184 was added to Linux in kernel 2.6.16;
 185 library support was added to glibc in version 2.4.
 186 .SH CONFORMING TO
 187 POSIX.1-2008.
 188 .SH NOTES
 189 See
 190 .BR openat (2)
 191 for an explanation of the need for
 192 .BR linkat ().
 193 .SH SEE ALSO
 194 .BR link (2),
 195 .BR openat (2),
 196 .BR path_resolution (7),
 197 .BR symlink (7)