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