lib/libc/sys/fhlink.2

   1 .\" SPDX-License-Identifier: BSD-2-Clause
   2 .\"
   3 .\" Copyright (c) 2018 Gandi
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 23, 2020
  29 .Dt FHLINK 2
  30 .Os
  31 .Sh NAME
  32 .Nm fhlink ,
  33 .Nm fhlinkat
  34 .Nd make a hard file link
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In unistd.h
  39 .Ft int
  40 .Fn fhlink "fhandle_t *fhp" "const char *to"
  41 .Ft int
  42 .Fn fhlinkat "fhandle_t *fhp" "int tofd" "const char *to"
  43 .Fc
  44 .Sh DESCRIPTION
  45 The
  46 .Fn fhlink
  47 system call
  48 atomically creates the specified directory entry (hard link)
  49 .Fa to
  50 with the attributes of the underlying object pointed at by
  51 .Fa fhp .
  52 If the link is successful: the link count of the underlying object
  53 is incremented;
  54 .Fa fhp
  55 and
  56 .Fa to
  57 share equal access and rights
  58 to the
  59 underlying object.
  60 .Pp
  61 If
  62 .Fa fhp
  63 is removed, the file
  64 .Fa to
  65 is not deleted and the link count of the
  66 underlying object is
  67 decremented.
  68 .Pp
  69 The object pointed at by the
  70 .Fa fhp
  71 argument
  72 must exist for the hard link to
  73 succeed and
  74 both
  75 .Fa fhp
  76 and
  77 .Fa to
  78 must be in the same file system.
  79 The
  80 .Fa fhp
  81 argument
  82 may not be a directory.
  83 .Pp
  84 The
  85 .Fn fhlinkat
  86 system call is equivalent to
  87 .Fa fhlink
  88 except in the case where
  89 .Fa to
  90 is a relative paths.
  91 In this case a relative path
  92 .Fa to
  93 is interpreted relative to
  94 the directory associated with the file descriptor
  95 .Fa tofd
  96 instead of the current working directory.
  97 .Pp
  98 Values for
  99 .Fa flag
 100 are constructed by a bitwise-inclusive OR of flags from the following
 101 list, defined in
 102 .In fcntl.h :
 103 .Bl -tag -width indent
 104 .It Dv AT_SYMLINK_FOLLOW
 105 If
 106 .Fa fhp
 107 names a symbolic link, a new link for the target of the symbolic link is
 108 created.
 109 .It Dv AT_BENEATH
 110 Only allow to link to a file which is beneath of the topping directory.
 111 See the description of the
 112 .Dv O_BENEATH
 113 flag in the
 114 .Xr open 2
 115 manual page.
 116 .It Dv AT_RESOLVE_BENEATH
 117 Only walks paths below the topping directory.
 118 See the description of the
 119 .Dv O_RESOLVE_BENEATH
 120 flag in the
 121 .Xr open 2
 122 manual page.
 123 .El
 124 .Pp
 125 If
 126 .Fn fhlinkat
 127 is passed the special value
 128 .Dv AT_FDCWD
 129 in the
 130 .Fa tofd
 131 parameter, the current working directory is used for the
 132 .Fa to
 133 argument.
 134 If
 135 .Fa tofd
 136 has value
 137 .Dv AT_FDCWD ,
 138 the behavior is identical to a call to
 139 .Fn link .
 140 Unless
 141 .Fa flag
 142 contains the
 143 .Dv AT_SYMLINK_FOLLOW
 144 flag, if
 145 .Fa fhp
 146 names a symbolic link, a new link is created for the symbolic link
 147 .Fa fhp
 148 and not its target.
 149 .Sh RETURN VALUES
 150 .Rv -std link
 151 .Sh ERRORS
 152 The
 153 .Fn fhlink
 154 system call
 155 will fail and no link will be created if:
 156 .Bl -tag -width Er
 157 .It Bq Er ENOTDIR
 158 A component of
 159 .Fa to
 160 prefix is not a directory.
 161 .It Bq Er ENAMETOOLONG
 162 A component of
 163 .Fa to
 164 exceeded 255 characters,
 165 or entire length of
 166 .Fa to
 167 name exceeded 1023 characters.
 168 .It Bq Er ENOENT
 169 A component of
 170 .Fa to
 171 prefix does not exist.
 172 .It Bq Er EOPNOTSUPP
 173 The file system containing the file pointed at by
 174 .Fa fhp
 175 does not support links.
 176 .It Bq Er EMLINK
 177 The link count of the file pointed at by
 178 .Fa fhp
 179 would exceed 32767.
 180 .It Bq Er EACCES
 181 A component of
 182 .Fa to
 183 prefix denies search permission.
 184 .It Bq Er EACCES
 185 The requested link requires writing in a directory with a mode
 186 that denies write permission.
 187 .It Bq Er ELOOP
 188 Too many symbolic links were encountered in translating one of the pathnames.
 189 .It Bq Er ENOENT
 190 The file pointed at by
 191 .Fa fhp
 192 does not exist.
 193 .It Bq Er EEXIST
 194 The link named by
 195 .Fa to
 196 does exist.
 197 .It Bq Er EPERM
 198 The file pointed at by
 199 .Fa fhp
 200 is a directory.
 201 .It Bq Er EPERM
 202 The file pointed at by
 203 .Fa fhp
 204 has its immutable or append-only flag set, see the
 205 .Xr chflags 2
 206 manual page for more information.
 207 .It Bq Er EPERM
 208 The parent directory of the file named by
 209 .Fa to
 210 has its immutable flag set.
 211 .It Bq Er EXDEV
 212 The link named by
 213 .Fa to
 214 and the file pointed at by
 215 .Fa fhp
 216 are on different file systems.
 217 .It Bq Er ENOSPC
 218 The directory in which the entry for the new link is being placed
 219 cannot be extended because there is no space left on the file
 220 system containing the directory.
 221 .It Bq Er EDQUOT
 222 The directory in which the entry for the new link
 223 is being placed cannot be extended because the
 224 user's quota of disk blocks on the file system
 225 containing the directory has been exhausted.
 226 .It Bq Er EIO
 227 An I/O error occurred while reading from or writing to
 228 the file system to make the directory entry.
 229 .It Bq Er EINTEGRITY
 230 Corrupted data was detected while reading from the file system.
 231 .It Bq Er EROFS
 232 The requested link requires writing in a directory on a read-only file
 233 system.
 234 .It Bq Er EFAULT
 235 One of the pathnames specified
 236 is outside the process's allocated address space.
 237 .It Bq Er ESTALE
 238 The file handle
 239 .Fa fhp
 240 is no longer valid
 241 .El
 242 .Pp
 243 In addition to the errors returned by the
 244 .Fn fhlink ,
 245 the
 246 .Fn fhlinkat
 247 system call may fail if:
 248 .Bl -tag -width Er
 249 .It Bq Er EBADF
 250 The
 251 .Fa fhp
 252 or
 253 .Fa to
 254 argument does not specify an absolute path and the
 255 .Fa tofd
 256 argument, is not
 257 .Dv AT_FDCWD
 258 nor a valid file descriptor open for searching.
 259 .It Bq Er EINVAL
 260 The value of the
 261 .Fa flag
 262 argument is not valid.
 263 .It Bq Er ENOTDIR
 264 The
 265 .Fa fhp
 266 or
 267 .Fa to
 268 argument is not an absolute path and
 269 .Fa tofd
 270 is not
 271 .Dv AT_FDCWD
 272 nor a file descriptor associated with a directory.
 273 .El
 274 .Sh SEE ALSO
 275 .Xr fhopen 2 ,
 276 .Xr fhreadlink 2 ,
 277 .Xr fhstat 2