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-03-19 "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 must refer to a file other than a directory.
 139 The caller must have the
 140 .BR CAP_DAC_READ_SEARCH
 141 capability in order to use this flag;
 142 this prevents arbitrary users from creating hard links
 143 using file descriptors received via a UNIX domain socket
 144 (see the discussion of
 145 .BR SCM_RIGHTS
 146 in
 147 .BR unix (7)).
 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 .PP
 168 Before kernel 2.6.18, the
 169 .I flags
 170 argument was unused, and had to be specified as 0.
 171 .PP
 172 See
 173 .BR openat (2)
 174 for an explanation of the need for
 175 .BR linkat ().
 176 .SH RETURN VALUE
 177 On success, zero is returned.
 178 On error, \-1 is returned, and
 179 .I errno
 180 is set appropriately.
 181 .SH ERRORS
 182 .TP
 183 .B EACCES
 184 Write access to the directory containing
 185 .I newpath
 186 is denied, or search permission is denied for one of the directories
 187 in the path prefix of
 188 .I oldpath
 189 or
 190 .IR newpath .
 191 (See also
 192 .BR path_resolution (7).)
 193 .TP
 194 .B EDQUOT
 195 The user's quota of disk blocks on the filesystem has been exhausted.
 196 .TP
 197 .B EEXIST
 198 .I newpath
 199 already exists.
 200 .TP
 201 .B EFAULT
 202 .IR oldpath " or " newpath " points outside your accessible address space."
 203 .TP
 204 .B EIO
 205 An I/O error occurred.
 206 .TP
 207 .B ELOOP
 208 Too many symbolic links were encountered in resolving
 209 .IR oldpath " or " newpath .
 210 .TP
 211 .B EMLINK
 212 The file referred to by
 213 .I oldpath
 214 already has the maximum number of links to it.
 215 .TP
 216 .B ENAMETOOLONG
 217 .IR oldpath " or " newpath " was too long."
 218 .TP
 219 .B ENOENT
 220 A directory component in
 221 .IR oldpath " or " newpath
 222 does not exist or is a dangling symbolic link.
 223 .TP
 224 .B ENOMEM
 225 Insufficient kernel memory was available.
 226 .TP
 227 .B ENOSPC
 228 The device containing the file has no room for the new directory
 229 entry.
 230 .TP
 231 .B ENOTDIR
 232 A component used as a directory in
 233 .IR oldpath " or " newpath
 234 is not, in fact, a directory.
 235 .TP
 236 .B EPERM
 237 .I oldpath
 238 is a directory.
 239 .TP
 240 .B EPERM
 241 The filesystem containing
 242 .IR oldpath " and " newpath
 243 does not support the creation of hard links.
 244 .TP
 245 .BR EPERM " (since Linux 3.6)"
 246 The caller does not have permission to create a hard link to this file
 247 (see the description of
 248 .IR /proc/sys/fs/protected_hardlinks
 249 in
 250 .BR proc (5)).
 251 .TP
 252 .B EROFS
 253 The file is on a read-only filesystem.
 254 .TP
 255 .B EXDEV
 256 .IR oldpath " and " newpath
 257 are not on the same mounted filesystem.
 258 (Linux permits a filesystem to be mounted at multiple points, but
 259 .BR link ()
 260 does not work across different mount points,
 261 even if the same filesystem is mounted on both.)
 262 .PP
 263 The following additional errors can occur for
 264 .BR linkat ():
 265 .TP
 266 .B EBADF
 267 .I olddirfd
 268 or
 269 .I newdirfd
 270 is not a valid file descriptor.
 271 .TP
 272 .B EINVAL
 273 An invalid flag value was specified in
 274 .IR flags .
 275 .TP
 276 .B ENOENT
 277 .B AT_EMPTY_PATH
 278 was specified in
 279 .IR flags ,
 280 but the caller did not have the
 281 .B CAP_DAC_READ_SEARCH
 282 capability.
 283 .TP
 284 .B ENOENT
 285 An attempt was made to link to the
 286 .I /proc/self/fd/NN
 287 file corresponding to a file descriptor created with
 288
 289     open(path, O_TMPFILE | O_EXCL, mode);
 290
 291 See
 292 .BR open (2).
 293 .TP
 294 .B ENOTDIR
 295 .I oldpath
 296 is relative and
 297 .I olddirfd
 298 is a file descriptor referring to a file other than a directory;
 299 or similar for
 300 .I newpath
 301 and
 302 .I newdirfd
 303 .TP
 304 .B EPERM
 305 .BR AT_EMPTY_PATH
 306 was specified in
 307 .IR flags ,
 308 .I oldpath
 309 is an empty string, and
 310 .IR olddirfd
 311 refers to a directory.
 312 .SH VERSIONS
 313 .BR linkat ()
 314 was added to Linux in kernel 2.6.16;
 315 library support was added to glibc in version 2.4.
 316 .SH CONFORMING TO
 317 .BR link ():
 318 SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES), POSIX.1-2008.
 319 .\" SVr4 documents additional ENOLINK and
 320 .\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP.
 321 .\" X/OPEN does not document EFAULT, ENOMEM or EIO.
 322
 323 .BR linkat ():
 324 POSIX.1-2008.
 325 .SH NOTES
 326 Hard links, as created by
 327 .BR link (),
 328 cannot span filesystems.
 329 Use
 330 .BR symlink (2)
 331 if this is required.
 332
 333 POSIX.1-2001 says that
 334 .BR link ()
 335 should dereference
 336 .I oldpath
 337 if it is a symbolic link.
 338 However, since kernel 2.0,
 339 .\" more precisely: since kernel 1.3.56
 340 Linux does not do so: if
 341 .I oldpath
 342 is a symbolic link, then
 343 .I newpath
 344 is created as a (hard) link to the same symbolic link file
 345 (i.e.,
 346 .I newpath
 347 becomes a symbolic link to the same file that
 348 .I oldpath
 349 refers to).
 350 Some other implementations behave in the same manner as Linux.
 351 .\" For example, the default Solaris compilation environment
 352 .\" behaves like Linux, and contributors to a March 2005
 353 .\" thread in the Austin mailing list reported that some
 354 .\" other (System V) implementations did/do the same -- MTK, Apr 05
 355 POSIX.1-2008 changes the specification of
 356 .BR link (),
 357 making it implementation-dependent whether or not
 358 .I oldpath
 359 is dereferenced if it is a symbolic link.
 360 For precise control over the treatment of symbolic links when
 361 creating a link, use
 362 .BR linkat (2).
 363 .SH BUGS
 364 On NFS filesystems, the return code may be wrong in case the NFS server
 365 performs the link creation and dies before it can say so.
 366 Use
 367 .BR stat (2)
 368 to find out if the link got created.
 369 .SH SEE ALSO
 370 .BR ln (1),
 371 .BR open (2),
 372 .BR rename (2),
 373 .BR stat (2),
 374 .BR symlink (2),
 375 .BR unlink (2),
 376 .BR path_resolution (7),
 377 .BR symlink (7)
 378 .SH COLOPHON
 379 This page is part of release 3.65 of the Linux
 380 .I man-pages
 381 project.
 382 A description of the project,
 383 and information about reporting bugs,
 384 can be found at
 385 \%http://www.kernel.org/doc/man\-pages/.