lib/libc/sys/link.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)link.2      8.3 (Berkeley) 1/12/94
  33 .\" $FreeBSD: src/lib/libc/sys/link.2,v 1.11.2.7 2001/12/14 18:34:01 ru Exp $
  34 .\"
  35 .Dd July 31, 2012
  36 .Dt LINK 2
  37 .Os
  38 .Sh NAME
  39 .Nm link ,
  40 .Nm linkat
  41 .Nd make a hard file link
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In unistd.h
  46 .Ft int
  47 .Fn link "const char *name1" "const char *name2"
  48 .Ft int
  49 .Fn linkat "int fd1" "const char *name1" "int fd2" "const char *name2" "int flags"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn link
  53 function call
  54 atomically creates the specified directory entry (hard link)
  55 .Fa name2
  56 with the attributes of the underlying object pointed at by
  57 .Fa name1 .
  58 If the link is successful: the link count of the underlying object
  59 is incremented;
  60 .Fa name1
  61 and
  62 .Fa name2
  63 share equal access and rights
  64 to the
  65 underlying object.
  66 .Pp
  67 If
  68 .Fa name1
  69 is removed, the file
  70 .Fa name2
  71 is not deleted and the link count of the
  72 underlying object is
  73 decremented.
  74 .Pp
  75 .Fa Name1
  76 must exist for the hard link to
  77 succeed and
  78 both
  79 .Fa name1
  80 and
  81 .Fa name2
  82 must be in the same file system.
  83 .Fa name1
  84 may not be a directory.
  85 .Pp
  86 When operating on a symlink,
  87 .Fn link
  88 resolves the symlink and creates a hard link on the target.
  89 .Fn linkat
  90 will do the same if
  91 .Dv AT_SYMLINK_FOLLOW
  92 is set in
  93 .Fa flags ,
  94 but it will link on the symlink itself if the flag is clear.
  95 .Pp
  96 The
  97 .Fn linkat
  98 system call is equivalent to
  99 .Fn link
 100 except in the case where either
 101 .Fa name1
 102 or
 103 .Fa name2
 104 or both are relative paths.
 105 In this case a relative path
 106 .Fa name1
 107 is interpreted relative to the directory associated with the file descriptor
 108 .Fa fd1
 109 instead of the current working directory and similarly for
 110 .Fa name2
 111 and the file descriptor
 112 .Fa fd2 .
 113 If
 114 .Fa fd1
 115 or
 116 .Fa fd2
 117 has the special value
 118 .Dv AT_FDCWD
 119 then
 120 .Fa name1
 121 or
 122 .Fa name2
 123 respectively is interpreted relative to the current working directory.
 124 .Sh RETURN VALUES
 125 .Rv -std link
 126 .Sh ERRORS
 127 .Fn Link
 128 will fail and no link will be created if:
 129 .Bl -tag -width Er
 130 .It Bq Er ENOTDIR
 131 A component of either path prefix is not a directory.
 132 .It Bq Er ENAMETOOLONG
 133 A component of either pathname exceeded 255 characters,
 134 or entire length of either path name exceeded 1023 characters.
 135 .It Bq Er ENOENT
 136 A component of either path prefix does not exist.
 137 .It Bq Er EOPNOTSUPP
 138 The file system containing the file named by
 139 .Fa name1
 140 does not support links.
 141 .It Bq Er EMLINK
 142 The link count of the file named by
 143 .Fa name1
 144 would exceed 32767.
 145 .It Bq Er EACCES
 146 A component of either path prefix denies search permission.
 147 .It Bq Er EACCES
 148 The requested link requires writing in a directory with a mode
 149 that denies write permission.
 150 .It Bq Er ELOOP
 151 Too many symbolic links were encountered in translating one of the pathnames.
 152 .It Bq Er ENOENT
 153 The file named by
 154 .Fa name1
 155 does not exist.
 156 .It Bq Er EEXIST
 157 The link named by
 158 .Fa name2
 159 does exist.
 160 .It Bq Er EPERM
 161 The named file has its immutable or append-only flag set (see
 162 .Xr chflags 2 ) .
 163 .It Bq Er EPERM
 164 The file named by
 165 .Fa name1
 166 is a directory.
 167 .It Bq Er EXDEV
 168 The link named by
 169 .Fa name2
 170 and the file named by
 171 .Fa name1
 172 are on different file systems.
 173 .It Bq Er ENOSPC
 174 The directory in which the entry for the new link is being placed
 175 cannot be extended because there is no space left on the file
 176 system containing the directory.
 177 .It Bq Er EDQUOT
 178 The directory in which the entry for the new link
 179 is being placed cannot be extended because the
 180 user's quota of disk blocks on the file system
 181 containing the directory has been exhausted.
 182 .It Bq Er EIO
 183 An I/O error occurred while reading from or writing to
 184 the file system to make the directory entry.
 185 .It Bq Er EROFS
 186 The requested link requires writing in a directory on a read-only file
 187 system.
 188 .It Bq Er EFAULT
 189 One of the pathnames specified
 190 is outside the process's allocated address space.
 191 .El
 192 .Pp
 193 In addition to the errors returned by the
 194 .Fn link
 195 syscall, the
 196 .Fn linkat
 197 system call may fail if:
 198 .Bl -tag -width Er
 199 .It Bq Er EBADF
 200 The
 201 .Fa name1
 202 or
 203 .Fa name2
 204 argument does not specify an absolute path and the
 205 .Fa fd1
 206 or
 207 .Fa fd2
 208 argument, respectively, is neither
 209 .Dv AT_FDCWD
 210 nor a valid file descriptor open for searching.
 211 .It Bq Er ENOTDIR
 212 The
 213 .Fa name1
 214 or
 215 .Fa name2
 216 argument is not an absolute path and
 217 .Fa fd1
 218 or
 219 .Fa fd2 ,
 220 respectively, is neither
 221 .Dv AT_FDCWD
 222 nor a file descriptor associated with a directory.
 223 .El
 224 .Sh SEE ALSO
 225 .Xr readlink 2 ,
 226 .Xr symlink 2 ,
 227 .Xr unlink 2
 228 .Sh STANDARDS
 229 The
 230 .Fn link
 231 function call is expected to conform to
 232 .St -p1003.1-90 .
 233 .Sh HISTORY
 234 A
 235 .Fn link
 236 function call appeared in
 237 .At v7 .
 238 The
 239 .Fn linkat
 240 system call appeared in
 241 .Dx 3.1 .
 242 .Pp
 243 The
 244 .Fn link
 245 system call traditionally allows the super-user to link directories which
 246 corrupts the filesystem coherency.  This implementation no longer permits
 247 it.