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