man2/link.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\"             and Copyright (C) 1993 Michael Haardt, Ian Jackson.
   3 .\" and Copyright (C) 2006, 2014 Michael Kerrisk
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
   8 .\" Modified 1994-08-21 by Michael Haardt
   9 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  10 .\" Modified 2005-04-04, as per suggestion by Michael Hardt for rename.2
  11 .\"
  12 .TH link 2 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 link, linkat \- make a new name for a file
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <unistd.h>
  21 .PP
  22 .BI "int link(const char *" oldpath ", const char *" newpath );
  23 .PP
  24 .BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
  25 .B #include <unistd.h>
  26 .PP
  27 .BI "int linkat(int " olddirfd ", const char *" oldpath ,
  28 .BI "           int " newdirfd ", const char *" newpath ", int " flags );
  29 .fi
  30 .PP
  31 .RS -4
  32 Feature Test Macro Requirements for glibc (see
  33 .BR feature_test_macros (7)):
  34 .RE
  35 .PP
  36 .BR linkat ():
  37 .nf
  38     Since glibc 2.10:
  39         _POSIX_C_SOURCE >= 200809L
  40     Before glibc 2.10:
  41         _ATFILE_SOURCE
  42 .fi
  43 .SH DESCRIPTION
  44 .BR link ()
  45 creates a new link (also known as a hard link) to an existing file.
  46 .PP
  47 If
  48 .I newpath
  49 exists, it will
  50 .I not
  51 be overwritten.
  52 .PP
  53 This new name may be used exactly as the old one for any operation;
  54 both names refer to the same file (and so have the same permissions
  55 and ownership) and it is impossible to tell which name was the
  56 "original".
  57 .SS linkat()
  58 The
  59 .BR linkat ()
  60 system call operates in exactly the same way as
  61 .BR link (),
  62 except for the differences described here.
  63 .PP
  64 If the pathname given in
  65 .I oldpath
  66 is relative, then it is interpreted relative to the directory
  67 referred to by the file descriptor
  68 .I olddirfd
  69 (rather than relative to the current working directory of
  70 the calling process, as is done by
  71 .BR link ()
  72 for a relative pathname).
  73 .PP
  74 If
  75 .I oldpath
  76 is relative and
  77 .I olddirfd
  78 is the special value
  79 .BR AT_FDCWD ,
  80 then
  81 .I oldpath
  82 is interpreted relative to the current working
  83 directory of the calling process (like
  84 .BR link ()).
  85 .PP
  86 If
  87 .I oldpath
  88 is absolute, then
  89 .I olddirfd
  90 is ignored.
  91 .PP
  92 The interpretation of
  93 .I newpath
  94 is as for
  95 .IR oldpath ,
  96 except that a relative pathname is interpreted relative
  97 to the directory referred to by the file descriptor
  98 .IR newdirfd .
  99 .PP
 100 The following values can be bitwise ORed in
 101 .IR flags :
 102 .TP
 103 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
 104 .\" commit 11a7b371b64ef39fc5fb1b6f2218eef7c4d035e3
 105 If
 106 .I oldpath
 107 is an empty string, create a link to the file referenced by
 108 .I olddirfd
 109 (which may have been obtained using the
 110 .BR open (2)
 111 .B O_PATH
 112 flag).
 113 In this case,
 114 .I olddirfd
 115 can refer to any type of file except a directory.
 116 This will generally not work if the file has a link count of zero (files
 117 created with
 118 .B O_TMPFILE
 119 and without
 120 .B O_EXCL
 121 are an exception).
 122 The caller must have the
 123 .B CAP_DAC_READ_SEARCH
 124 capability in order to use this flag.
 125 This flag is Linux-specific; define
 126 .B _GNU_SOURCE
 127 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
 128 to obtain its definition.
 129 .TP
 130 .BR AT_SYMLINK_FOLLOW " (since Linux 2.6.18)"
 131 By default,
 132 .BR linkat (),
 133 does not dereference
 134 .I oldpath
 135 if it is a symbolic link (like
 136 .BR link ()).
 137 The flag
 138 .B AT_SYMLINK_FOLLOW
 139 can be specified in
 140 .I flags
 141 to cause
 142 .I oldpath
 143 to be dereferenced if it is a symbolic link.
 144 If procfs is mounted,
 145 this can be used as an alternative to
 146 .BR AT_EMPTY_PATH ,
 147 like this:
 148 .IP
 149 .in +4n
 150 .EX
 151 linkat(AT_FDCWD, "/proc/self/fd/<fd>", newdirfd,
 152        newname, AT_SYMLINK_FOLLOW);
 153 .EE
 154 .in
 155 .PP
 156 Before kernel 2.6.18, the
 157 .I flags
 158 argument was unused, and had to be specified as 0.
 159 .PP
 160 See
 161 .BR openat (2)
 162 for an explanation of the need for
 163 .BR linkat ().
 164 .SH RETURN VALUE
 165 On success, zero is returned.
 166 On error, \-1 is returned, and
 167 .I errno
 168 is set to indicate the error.
 169 .SH ERRORS
 170 .TP
 171 .B EACCES
 172 Write access to the directory containing
 173 .I newpath
 174 is denied, or search permission is denied for one of the directories
 175 in the path prefix of
 176 .I oldpath
 177 or
 178 .IR newpath .
 179 (See also
 180 .BR path_resolution (7).)
 181 .TP
 182 .B EDQUOT
 183 The user's quota of disk blocks on the filesystem has been exhausted.
 184 .TP
 185 .B EEXIST
 186 .I newpath
 187 already exists.
 188 .TP
 189 .B EFAULT
 190 .IR oldpath " or " newpath " points outside your accessible address space."
 191 .TP
 192 .B EIO
 193 An I/O error occurred.
 194 .TP
 195 .B ELOOP
 196 Too many symbolic links were encountered in resolving
 197 .IR oldpath " or " newpath .
 198 .TP
 199 .B EMLINK
 200 The file referred to by
 201 .I oldpath
 202 already has the maximum number of links to it.
 203 For example, on an
 204 .BR ext4 (5)
 205 filesystem that does not employ the
 206 .I dir_index
 207 feature, the limit on the number of hard links to a file is 65,000; on
 208 .BR btrfs (5),
 209 the limit is 65,535 links.
 210 .TP
 211 .B ENAMETOOLONG
 212 .IR oldpath " or " newpath " was too long."
 213 .TP
 214 .B ENOENT
 215 A directory component in
 216 .IR oldpath " or " newpath
 217 does not exist or is a dangling symbolic link.
 218 .TP
 219 .B ENOMEM
 220 Insufficient kernel memory was available.
 221 .TP
 222 .B ENOSPC
 223 The device containing the file has no room for the new directory
 224 entry.
 225 .TP
 226 .B ENOTDIR
 227 A component used as a directory in
 228 .IR oldpath " or " newpath
 229 is not, in fact, a directory.
 230 .TP
 231 .B EPERM
 232 .I oldpath
 233 is a directory.
 234 .TP
 235 .B EPERM
 236 The filesystem containing
 237 .IR oldpath " and " newpath
 238 does not support the creation of hard links.
 239 .TP
 240 .BR EPERM " (since Linux 3.6)"
 241 The caller does not have permission to create a hard link to this file
 242 (see the description of
 243 .I /proc/sys/fs/protected_hardlinks
 244 in
 245 .BR proc (5)).
 246 .TP
 247 .B EPERM
 248 .I oldpath
 249 is marked immutable or append-only.
 250 (See
 251 .BR ioctl_iflags (2).)
 252 .TP
 253 .B EROFS
 254 The file is on a read-only filesystem.
 255 .TP
 256 .B EXDEV
 257 .IR oldpath " and " newpath
 258 are not on the same mounted filesystem.
 259 (Linux permits a filesystem to be mounted at multiple points, but
 260 .BR link ()
 261 does not work across different mounts,
 262 even if the same filesystem is mounted on both.)
 263 .PP
 264 The following additional errors can occur for
 265 .BR linkat ():
 266 .TP
 267 .B EBADF
 268 .I oldpath
 269 .RI ( newpath )
 270 is relative but
 271 .I olddirfd
 272 .RI ( newdirfd )
 273 is neither
 274 .B AT_FDCWD
 275 nor a valid file descriptor.
 276 .TP
 277 .B EINVAL
 278 An invalid flag value was specified in
 279 .IR flags .
 280 .TP
 281 .B ENOENT
 282 .B AT_EMPTY_PATH
 283 was specified in
 284 .IR flags ,
 285 but the caller did not have the
 286 .B CAP_DAC_READ_SEARCH
 287 capability.
 288 .TP
 289 .B ENOENT
 290 An attempt was made to link to the
 291 .I /proc/self/fd/NN
 292 file corresponding to a file descriptor created with
 293 .IP
 294 .in +4n
 295 .EX
 296 open(path, O_TMPFILE | O_EXCL, mode);
 297 .EE
 298 .in
 299 .IP
 300 See
 301 .BR open (2).
 302 .TP
 303 .B ENOENT
 304 An attempt was made to link to a
 305 .I /proc/self/fd/NN
 306 file corresponding to a file that has been deleted.
 307 .TP
 308 .B ENOENT
 309 .I oldpath
 310 is a relative pathname and
 311 .I olddirfd
 312 refers to a directory that has been deleted,
 313 or
 314 .I newpath
 315 is a relative pathname and
 316 .I newdirfd
 317 refers to a directory that has been deleted.
 318 .TP
 319 .B ENOTDIR
 320 .I oldpath
 321 is relative and
 322 .I olddirfd
 323 is a file descriptor referring to a file other than a directory;
 324 or similar for
 325 .I newpath
 326 and
 327 .I newdirfd
 328 .TP
 329 .B EPERM
 330 .B AT_EMPTY_PATH
 331 was specified in
 332 .IR flags ,
 333 .I oldpath
 334 is an empty string, and
 335 .I olddirfd
 336 refers to a directory.
 337 .SH VERSIONS
 338 .BR linkat ()
 339 was added to Linux in kernel 2.6.16;
 340 library support was added to glibc in version 2.4.
 341 .SH STANDARDS
 342 .BR link ():
 343 SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES), POSIX.1-2008.
 344 .\" SVr4 documents additional ENOLINK and
 345 .\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP.
 346 .\" X/OPEN does not document EFAULT, ENOMEM or EIO.
 347 .PP
 348 .BR linkat ():
 349 POSIX.1-2008.
 350 .SH NOTES
 351 Hard links, as created by
 352 .BR link (),
 353 cannot span filesystems.
 354 Use
 355 .BR symlink (2)
 356 if this is required.
 357 .PP
 358 POSIX.1-2001 says that
 359 .BR link ()
 360 should dereference
 361 .I oldpath
 362 if it is a symbolic link.
 363 However, since kernel 2.0,
 364 .\" more precisely: since kernel 1.3.56
 365 Linux does not do so: if
 366 .I oldpath
 367 is a symbolic link, then
 368 .I newpath
 369 is created as a (hard) link to the same symbolic link file
 370 (i.e.,
 371 .I newpath
 372 becomes a symbolic link to the same file that
 373 .I oldpath
 374 refers to).
 375 Some other implementations behave in the same manner as Linux.
 376 .\" For example, the default Solaris compilation environment
 377 .\" behaves like Linux, and contributors to a March 2005
 378 .\" thread in the Austin mailing list reported that some
 379 .\" other (System V) implementations did/do the same -- MTK, Apr 05
 380 POSIX.1-2008 changes the specification of
 381 .BR link (),
 382 making it implementation-dependent whether or not
 383 .I oldpath
 384 is dereferenced if it is a symbolic link.
 385 For precise control over the treatment of symbolic links when
 386 creating a link, use
 387 .BR linkat ().
 388 .SS Glibc notes
 389 On older kernels where
 390 .BR linkat ()
 391 is unavailable, the glibc wrapper function falls back to the use of
 392 .BR link (),
 393 unless the
 394 .B AT_SYMLINK_FOLLOW
 395 is specified.
 396 When
 397 .I oldpath
 398 and
 399 .I newpath
 400 are relative pathnames,
 401 glibc constructs pathnames based on the symbolic links in
 402 .I /proc/self/fd
 403 that correspond to the
 404 .I olddirfd
 405 and
 406 .I newdirfd
 407 arguments.
 408 .SH BUGS
 409 On NFS filesystems, the return code may be wrong in case the NFS server
 410 performs the link creation and dies before it can say so.
 411 Use
 412 .BR stat (2)
 413 to find out if the link got created.
 414 .SH SEE ALSO
 415 .BR ln (1),
 416 .BR open (2),
 417 .BR rename (2),
 418 .BR stat (2),
 419 .BR symlink (2),
 420 .BR unlink (2),
 421 .BR path_resolution (7),
 422 .BR symlink (7)