original/man2/link.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\"             and Copyright (C) 1993 Michael Haardt, Ian Jackson.
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
  27 .\" Modified 1994-08-21 by Michael Haardt
  28 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  29 .\" Modified 2005-04-04, as per suggestion by Michael Hardt for rename.2
  30 .\"
  31 .TH LINK 2 2013-01-27 "Linux" "Linux Programmer's Manual"
  32 .SH NAME
  33 link \- make a new name for a file
  34 .SH SYNOPSIS
  35 .B #include <unistd.h>
  36 .sp
  37 .BI "int link(const char *" oldpath ", const char *" newpath );
  38 .SH DESCRIPTION
  39 .BR link ()
  40 creates a new link (also known as a hard link) to an existing file.
  41
  42 If
  43 .I newpath
  44 exists it will
  45 .I not
  46 be overwritten.
  47
  48 This new name may be used exactly as the old one for any operation;
  49 both names refer to the same file (and so have the same permissions
  50 and ownership) and it is impossible to tell which name was the
  51 "original".
  52 .SH RETURN VALUE
  53 On success, zero is returned.
  54 On error, \-1 is returned, and
  55 .I errno
  56 is set appropriately.
  57 .SH ERRORS
  58 .TP
  59 .B EACCES
  60 Write access to the directory containing
  61 .I newpath
  62 is denied, or search permission is denied for one of the directories
  63 in the path prefix of
  64 .I oldpath
  65 or
  66 .IR newpath .
  67 (See also
  68 .BR path_resolution (7).)
  69 .TP
  70 .B EDQUOT
  71 The user's quota of disk blocks on the filesystem has been exhausted.
  72 .TP
  73 .B EEXIST
  74 .I newpath
  75 already exists.
  76 .TP
  77 .B EFAULT
  78 .IR oldpath " or " newpath " points outside your accessible address space."
  79 .TP
  80 .B EIO
  81 An I/O error occurred.
  82 .TP
  83 .B ELOOP
  84 Too many symbolic links were encountered in resolving
  85 .IR oldpath " or " newpath .
  86 .TP
  87 .B EMLINK
  88 The file referred to by
  89 .I oldpath
  90 already has the maximum number of links to it.
  91 .TP
  92 .B ENAMETOOLONG
  93 .IR oldpath " or " newpath " was too long."
  94 .TP
  95 .B ENOENT
  96 A directory component in
  97 .IR oldpath " or " newpath
  98 does not exist or is a dangling symbolic link.
  99 .TP
 100 .B ENOMEM
 101 Insufficient kernel memory was available.
 102 .TP
 103 .B ENOSPC
 104 The device containing the file has no room for the new directory
 105 entry.
 106 .TP
 107 .B ENOTDIR
 108 A component used as a directory in
 109 .IR oldpath " or " newpath
 110 is not, in fact, a directory.
 111 .TP
 112 .B EPERM
 113 .I oldpath
 114 is a directory.
 115 .TP
 116 .B EPERM
 117 The filesystem containing
 118 .IR oldpath " and " newpath
 119 does not support the creation of hard links.
 120 .TP
 121 .BR EPERM " (since Linux 3.6)"
 122 The caller does not have permission to create a hard link to this file
 123 (see the description of
 124 .IR /proc/sys/fs/protected_hardlink
 125 in
 126 .BR proc (5)).
 127 .TP
 128 .B EROFS
 129 The file is on a read-only filesystem.
 130 .TP
 131 .B EXDEV
 132 .IR oldpath " and " newpath
 133 are not on the same mounted filesystem.
 134 (Linux permits a filesystem to be mounted at multiple points, but
 135 .BR link ()
 136 does not work across different mount points,
 137 even if the same filesystem is mounted on both.)
 138 .SH CONFORMING TO
 139 SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES).
 140 .\" SVr4 documents additional ENOLINK and
 141 .\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP.
 142 .\" X/OPEN does not document EFAULT, ENOMEM or EIO.
 143 .SH NOTES
 144 Hard links, as created by
 145 .BR link (),
 146 cannot span filesystems.
 147 Use
 148 .BR symlink (2)
 149 if this is required.
 150
 151 POSIX.1-2001 says that
 152 .BR link ()
 153 should dereference
 154 .I oldpath
 155 if it is a symbolic link.
 156 However, since kernel 2.0,
 157 .\" more precisely: since kernel 1.3.56
 158 Linux does not do so: if
 159 .I oldpath
 160 is a symbolic link, then
 161 .I newpath
 162 is created as a (hard) link to the same symbolic link file
 163 (i.e.,
 164 .I newpath
 165 becomes a symbolic link to the same file that
 166 .I oldpath
 167 refers to).
 168 Some other implementations behave in the same manner as Linux.
 169 .\" For example, the default Solaris compilation environment
 170 .\" behaves like Linux, and contributors to a March 2005
 171 .\" thread in the Austin mailing list reported that some
 172 .\" other (System V) implementations did/do the same -- MTK, Apr 05
 173 POSIX.1-2008 changes the specification of
 174 .BR link (),
 175 making it implementation-dependent whether or not
 176 .I oldpath
 177 is dereferenced if it is a symbolic link.
 178 For precise control over the treatment of symbolic links when
 179 creating a link, see
 180 .BR linkat (2).
 181 .SH BUGS
 182 On NFS filesystems, the return code may be wrong in case the NFS server
 183 performs the link creation and dies before it can say so.
 184 Use
 185 .BR stat (2)
 186 to find out if the link got created.
 187 .SH SEE ALSO
 188 .BR ln (1),
 189 .BR linkat (2),
 190 .BR open (2),
 191 .BR rename (2),
 192 .BR stat (2),
 193 .BR symlink (2),
 194 .BR unlink (2),
 195 .BR path_resolution (7),
 196 .BR symlink (7)