original/man2/link.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   4 .\"                               1993 Michael Haardt, Ian Jackson.
   5 .\"
   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 .\"
  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 2008-08-21 "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 EEXIST
  71 .I newpath
  72 already exists.
  73 .TP
  74 .B EFAULT
  75 .IR oldpath " or " newpath " points outside your accessible address space."
  76 .TP
  77 .B EIO
  78 An I/O error occurred.
  79 .TP
  80 .B ELOOP
  81 Too many symbolic links were encountered in resolving
  82 .IR oldpath " or " newpath .
  83 .TP
  84 .B EMLINK
  85 The file referred to by
  86 .I oldpath
  87 already has the maximum number of links to it.
  88 .TP
  89 .B ENAMETOOLONG
  90 .IR oldpath " or " newpath " was too long."
  91 .TP
  92 .B ENOENT
  93 A directory component in
  94 .IR oldpath " or " newpath
  95 does not exist or is a dangling symbolic link.
  96 .TP
  97 .B ENOMEM
  98 Insufficient kernel memory was available.
  99 .TP
 100 .B ENOSPC
 101 The device containing the file has no room for the new directory
 102 entry.
 103 .TP
 104 .B ENOTDIR
 105 A component used as a directory in
 106 .IR oldpath " or " newpath
 107 is not, in fact, a directory.
 108 .TP
 109 .B EPERM
 110 .I oldpath
 111 is a directory.
 112 .TP
 113 .B EPERM
 114 The file system containing
 115 .IR oldpath " and " newpath
 116 does not support the creation of hard links.
 117 .TP
 118 .B EROFS
 119 The file is on a read-only file system.
 120 .TP
 121 .B EXDEV
 122 .IR oldpath " and " newpath
 123 are not on the same mounted file system.
 124 (Linux permits a file system to be mounted at multiple points, but
 125 .BR link ()
 126 does not work across different mount points,
 127 even if the same file system is mounted on both.)
 128 .SH "CONFORMING TO"
 129 SVr4, 4.3BSD, POSIX.1-2001 (but see NOTES).
 130 .\" SVr4 documents additional ENOLINK and
 131 .\" EMULTIHOP error conditions; POSIX.1 does not document ELOOP.
 132 .\" X/OPEN does not document EFAULT, ENOMEM or EIO.
 133 .SH NOTES
 134 Hard links, as created by
 135 .BR link (),
 136 cannot span file systems.
 137 Use
 138 .BR symlink (2)
 139 if this is required.
 140
 141 POSIX.1-2001 says that
 142 .BR link ()
 143 should dereference
 144 .I oldpath
 145 if it is a symbolic link.
 146 However, since kernel 2.0,
 147 .\" more precisely: since kernel 1.3.56
 148 Linux does not do so: if
 149 .I oldpath
 150 is a symbolic link, then
 151 .I newpath
 152 is created as a (hard) link to the same symbolic link file
 153 (i.e.,
 154 .I newpath
 155 becomes a symbolic link to the same file that
 156 .I oldpath
 157 refers to).
 158 Some other implementations behave in the same manner as Linux.
 159 .\" For example, the default Solaris compilation environment
 160 .\" behaves like Linux, and contributors to a March 2005
 161 .\" thread in the Austin mailing list reported that some
 162 .\" other (System V) implementations did/do the same -- MTK, Apr 05
 163 POSIX.1-2008 changes the specification of
 164 .BR link (),
 165 making it implementation-dependent whether or not
 166 .I oldpath
 167 is dereferenced if it is a symbolic link.
 168 For precise control over the treatment of symbolic links when
 169 creating a link, see
 170 .BR linkat (2).
 171 .SH BUGS
 172 On NFS file systems, the return code may be wrong in case the NFS server
 173 performs the link creation and dies before it can say so.
 174 Use
 175 .BR stat (2)
 176 to find out if the link got created.
 177 .SH "SEE ALSO"
 178 .BR ln (1),
 179 .BR linkat (2),
 180 .BR open (2),
 181 .BR rename (2),
 182 .BR stat (2),
 183 .BR symlink (2),
 184 .BR unlink (2),
 185 .BR path_resolution (7),
 186 .BR symlink (7)