bsd/man/man2/link.2

   1 .\"     $NetBSD: link.2,v 1.7 1995/02/27 12:34:01 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)link.2      8.3 (Berkeley) 1/12/94
  35 .\"
  36 .Dd October 29, 2008
  37 .Dt LINK 2
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm link ,
  41 .Nm linkat
  42 .Nd make a hard file link
  43 .Sh SYNOPSIS
  44 .Fd #include <unistd.h>
  45 .Ft int
  46 .Fo link
  47 .Fa "const char *path1"
  48 .Fa "const char *path2"
  49 .Fc
  50 .Ft int
  51 .Fo linkat
  52 .Fa "int fd1" "const char *name1" "int fd2" "const char *name2" "int flag"
  53 .Fc
  54 .Sh DESCRIPTION
  55 The
  56 .Fn link
  57 function call
  58 atomically creates the specified directory entry (hard link)
  59 .Fa path2
  60 with the attributes of the underlying object pointed at by
  61 .Fa path1 .
  62 If the link is successful,
  63 the link count of the underlying object is incremented;
  64 .Fa path1
  65 and
  66 .Fa path2
  67 share equal access and rights
  68 to the
  69 underlying object.
  70 .Pp
  71 If
  72 .Fa path1
  73 is removed, the file
  74 .Fa path2
  75 is not deleted and the link count of the
  76 underlying object is
  77 decremented.
  78 .Pp
  79 In order for the system call to succeed,
  80 .Fa path1
  81 must exist and both
  82 .Fa path1
  83 and
  84 .Fa path2
  85 must be in the same file system.
  86 As mandated by POSIX.1,
  87 .Fa path1
  88 may not be a directory.
  89 .Pp
  90 .Fn link
  91 will resolve and follow symbolic links contained within both
  92 .Fa path1
  93 and
  94 .Fa path2 .
  95 If the last component of
  96 .Fa path1
  97 is a symbolic link,
  98 .Fn link
  99 will point the hard link,
 100 .Fa path2 ,
 101 to the underlying object pointed to by
 102 .Fa path1 ,
 103 not to the symbolic link itself.
 104 .Pp
 105 The
 106 .Fn linkat
 107 system call is equivalent to
 108 .Fa link
 109 except in the case where either
 110 .Fa name1
 111 or
 112 .Fa name2
 113 or both are relative paths.
 114 In this case a relative path
 115 .Fa name1
 116 is interpreted relative to
 117 the directory associated with the file descriptor
 118 .Fa fd1
 119 instead of the current working directory and similarly for
 120 .Fa name2
 121 and the file descriptor
 122 .Fa fd2 .
 123 .Pp
 124 Values for
 125 .Fa flag
 126 are constructed by a bitwise-inclusive OR of flags from the following
 127 list, defined in
 128 .In fcntl.h :
 129 .Bl -tag -width indent
 130 .It Dv AT_SYMLINK_FOLLOW
 131 If
 132 .Fa name1
 133 names a symbolic link, a new link for the target of the symbolic link is
 134 created.
 135 .El
 136 .Pp
 137 If
 138 .Fn linkat
 139 is passed the special value
 140 .Dv AT_FDCWD
 141 in the
 142 .Fa fd1
 143 or
 144 .Fa fd2
 145 parameter, the current working directory is used for the respective
 146 .Fa name
 147 argument.
 148 If both
 149 .Fa fd1
 150 and
 151 .Fa fd2
 152 have value
 153 .Dv AT_FDCWD ,
 154 the behavior is identical to a call to
 155 .Fn link .
 156 Unless
 157 .Fa flag
 158 contains the
 159 .Dv AT_SYMLINK_FOLLOW
 160 flag, if
 161 .Fa name1
 162 names a symbolic link, a new link is created for the symbolic link
 163 .Fa name1
 164 and not its target. On OS X, not assigning AT_SYMLINK_FOLLOW to
 165 .Fa flag
 166 may result in some filesystems returning an error.
 167 .Sh RETURN VALUES
 168 Upon successful completion, a value of 0 is returned.  Otherwise,
 169 a value of -1 is returned and
 170 .Va errno
 171 is set to indicate the error.
 172 .Sh ERRORS
 173 .Fn link
 174 will fail and no link will be created if:
 175 .Bl -tag -width Er
 176 .\" ==========
 177 .It Bq Er EACCES
 178 A component of either path prefix denies search permission.
 179 .\" ==========
 180 .It Bq Er EACCES
 181 The requested link requires writing in a directory with a mode
 182 that denies write permission.
 183 .\" ==========
 184 .It Bq Er EACCES
 185 The current process cannot access the existing file.
 186 .\" ==========
 187 .It Bq Er EDQUOT
 188 The directory in which the entry for the new link
 189 is being placed cannot be extended because the
 190 user's quota of disk blocks on the file system
 191 containing the directory has been exhausted.
 192 .\" ==========
 193 .It Bq Er EEXIST
 194 The link named by
 195 .Fa path2
 196 already exists.
 197 .\" ==========
 198 .It Bq Er EFAULT
 199 One of the pathnames specified
 200 is outside the process's allocated address space.
 201 .\" ==========
 202 .It Bq Er EIO
 203 An I/O error occurs while reading from or writing to
 204 the file system to make the directory entry.
 205 .\" ==========
 206 .It Bq Er ELOOP
 207 Too many symbolic links are encountered in translating one of the pathnames.
 208 This is taken to be indicative of a looping symbolic link.
 209 .\" ==========
 210 .It Bq Er EMLINK
 211 The file already has {LINK_MAX} links.
 212 .\" ==========
 213 .It Bq Er ENAMETOOLONG
 214 A component of a pathname exceeds
 215 .Dv {NAME_MAX}
 216 characters, or an entire path name exceeded
 217 .Dv {PATH_MAX}
 218 characters.
 219 .\" ==========
 220 .It Bq Er ENOENT
 221 A component of either path prefix does not exist, or is a dangling symbolic link.
 222 .\" ==========
 223 .It Bq Er ENOENT
 224 The file named by
 225 .Fa path1
 226 does not exist, or is a dangling symbolic link.
 227 .\" ==========
 228 .It Bq Er ENOSPC
 229 The directory in which the entry for the new link is being placed
 230 cannot be extended because there is no space left on the file
 231 system containing the directory.
 232 .\" ==========
 233 .It Bq Er ENOTDIR
 234 A component of either path prefix is not a directory.
 235 .\" ==========
 236 .It Bq Er EPERM
 237 The file named by
 238 .Fa path1
 239 is a directory.
 240 .\" ==========
 241 .It Bq Er EROFS
 242 The requested link requires writing in a directory
 243 on a read-only file system.
 244 .\" ==========
 245 .It Bq Er EXDEV
 246 The link named by
 247 .Fa path2
 248 and the file named by
 249 .Fa path1
 250 are on different file systems.
 251 .El
 252 .Pp
 253 In addition to the errors returned by the
 254 .Fn link ,
 255 the
 256 .Fn linkat
 257 system call may fail if:
 258 .Bl -tag -width Er
 259 .It Bq Er EBADF
 260 The
 261 .Fa name1
 262 or
 263 .Fa name2
 264 argument does not specify an absolute path and the
 265 .Fa fd1
 266 or
 267 .Fa fd2
 268 argument, respectively, is neither
 269 .Dv AT_FDCWD
 270 nor a valid file descriptor open for searching.
 271 .It Bq Er EINVAL
 272 The value of the
 273 .Fa flag
 274 argument is not valid.
 275 .It Bq Er ENOTSUP
 276 .Fa flag
 277 was not set to
 278 .Dv AT_SYMLINK_FOLLOW (some filesystems only)
 279 .It Bq Er ENOTDIR
 280 The
 281 .Fa name1
 282 or
 283 .Fa name2
 284 argument is not an absolute path and
 285 .Fa fd1
 286 or
 287 .Fa fd2 ,
 288 respectively, is neither
 289 .Dv AT_FDCWD
 290 nor a file descriptor associated with a directory.
 291 .El
 292 .Sh SEE ALSO
 293 .Xr symlink 2 ,
 294 .Xr unlink 2
 295 .Sh STANDARDS
 296 The
 297 .Fn link
 298 function is expected to conform to
 299 .St -p1003.1-88 .
 300 The
 301 .Fn linkat
 302 system call is expected to conform to POSIX.1-2008 .