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