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 .Dd November 30, 2022
  27 .Dt FHLINK 2
  28 .Os
  29 .Sh NAME
  30 .Nm fhlink ,
  31 .Nm fhlinkat
  32 .Nd make a hard file link
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In unistd.h
  37 .Ft int
  38 .Fn fhlink "fhandle_t *fhp" "const char *to"
  39 .Ft int
  40 .Fn fhlinkat "fhandle_t *fhp" "int tofd" "const char *to"
  41 .Fc
  42 .Sh DESCRIPTION
  43 The
  44 .Fn fhlink
  45 system call
  46 atomically creates the specified directory entry (hard link)
  47 .Fa to
  48 with the attributes of the underlying object pointed at by
  49 .Fa fhp .
  50 If the link is successful: the link count of the underlying object
  51 is incremented;
  52 .Fa fhp
  53 and
  54 .Fa to
  55 share equal access and rights
  56 to the
  57 underlying object.
  58 .Pp
  59 If
  60 .Fa fhp
  61 is removed, the file
  62 .Fa to
  63 is not deleted and the link count of the
  64 underlying object is
  65 decremented.
  66 .Pp
  67 The object pointed at by the
  68 .Fa fhp
  69 argument
  70 must exist for the hard link to
  71 succeed and
  72 both
  73 .Fa fhp
  74 and
  75 .Fa to
  76 must be in the same file system.
  77 The
  78 .Fa fhp
  79 argument
  80 may not be a directory.
  81 .Pp
  82 The
  83 .Fn fhlinkat
  84 system call is equivalent to
  85 .Fa fhlink
  86 except in the case where
  87 .Fa to
  88 is a relative paths.
  89 In this case a relative path
  90 .Fa to
  91 is interpreted relative to
  92 the directory associated with the file descriptor
  93 .Fa tofd
  94 instead of the current working directory.
  95 .Pp
  96 If
  97 .Fn fhlinkat
  98 is passed the special value
  99 .Dv AT_FDCWD
 100 in the
 101 .Fa tofd
 102 parameter, the current working directory is used for the
 103 .Fa to
 104 argument.
 105 If
 106 .Fa tofd
 107 has value
 108 .Dv AT_FDCWD ,
 109 the behavior is identical to a call to
 110 .Fn link .
 111 Unless
 112 .Fa flag
 113 contains the
 114 .Dv AT_SYMLINK_FOLLOW
 115 flag, if
 116 .Fa fhp
 117 names a symbolic link, a new link is created for the symbolic link
 118 .Fa fhp
 119 and not its target.
 120 .Sh RETURN VALUES
 121 .Rv -std link
 122 .Sh ERRORS
 123 The
 124 .Fn fhlink
 125 system call
 126 will fail and no link will be created if:
 127 .Bl -tag -width Er
 128 .It Bq Er ENOTDIR
 129 A component of
 130 .Fa to
 131 prefix is not a directory.
 132 .It Bq Er ENAMETOOLONG
 133 A component of
 134 .Fa to
 135 exceeded 255 characters,
 136 or entire length of
 137 .Fa to
 138 name exceeded 1023 characters.
 139 .It Bq Er ENOENT
 140 A component of
 141 .Fa to
 142 prefix does not exist.
 143 .It Bq Er EOPNOTSUPP
 144 The file system containing the file pointed at by
 145 .Fa fhp
 146 does not support links.
 147 .It Bq Er EMLINK
 148 The link count of the file pointed at by
 149 .Fa fhp
 150 would exceed 32767.
 151 .It Bq Er EACCES
 152 A component of
 153 .Fa to
 154 prefix denies search permission.
 155 .It Bq Er EACCES
 156 The requested link requires writing in a directory with a mode
 157 that denies write permission.
 158 .It Bq Er ELOOP
 159 Too many symbolic links were encountered in translating one of the pathnames.
 160 .It Bq Er ENOENT
 161 The file pointed at by
 162 .Fa fhp
 163 does not exist.
 164 .It Bq Er EEXIST
 165 The link named by
 166 .Fa to
 167 does exist.
 168 .It Bq Er EPERM
 169 The file pointed at by
 170 .Fa fhp
 171 is a directory.
 172 .It Bq Er EPERM
 173 The file pointed at by
 174 .Fa fhp
 175 has its immutable or append-only flag set, see the
 176 .Xr chflags 2
 177 manual page for more information.
 178 .It Bq Er EPERM
 179 The parent directory of the file named by
 180 .Fa to
 181 has its immutable flag set.
 182 .It Bq Er EXDEV
 183 The link named by
 184 .Fa to
 185 and the file pointed at by
 186 .Fa fhp
 187 are on different file systems.
 188 .It Bq Er ENOSPC
 189 The directory in which the entry for the new link is being placed
 190 cannot be extended because there is no space left on the file
 191 system containing the directory.
 192 .It Bq Er EDQUOT
 193 The directory in which the entry for the new link
 194 is being placed cannot be extended because the
 195 user's quota of disk blocks on the file system
 196 containing the directory has been exhausted.
 197 .It Bq Er EIO
 198 An I/O error occurred while reading from or writing to
 199 the file system to make the directory entry.
 200 .It Bq Er EINTEGRITY
 201 Corrupted data was detected while reading from the file system.
 202 .It Bq Er EROFS
 203 The requested link requires writing in a directory on a read-only file
 204 system.
 205 .It Bq Er EFAULT
 206 One of the pathnames specified
 207 is outside the process's allocated address space.
 208 .It Bq Er ESTALE
 209 The file handle
 210 .Fa fhp
 211 is no longer valid
 212 .El
 213 .Pp
 214 In addition to the errors returned by the
 215 .Fn fhlink ,
 216 the
 217 .Fn fhlinkat
 218 system call may fail if:
 219 .Bl -tag -width Er
 220 .It Bq Er EBADF
 221 The
 222 .Fa fhp
 223 or
 224 .Fa to
 225 argument does not specify an absolute path and the
 226 .Fa tofd
 227 argument, is not
 228 .Dv AT_FDCWD
 229 nor a valid file descriptor open for searching.
 230 .It Bq Er EINVAL
 231 The value of the
 232 .Fa flag
 233 argument is not valid.
 234 .It Bq Er ENOTDIR
 235 The
 236 .Fa fhp
 237 or
 238 .Fa to
 239 argument is not an absolute path and
 240 .Fa tofd
 241 is not
 242 .Dv AT_FDCWD
 243 nor a file descriptor associated with a directory.
 244 .El
 245 .Sh SEE ALSO
 246 .Xr fhopen 2 ,
 247 .Xr fhreadlink 2 ,
 248 .Xr fhstat 2
 249 .Sh HISTORY
 250 The
 251 .Fn fhlink
 252 and
 253 .Fn fhlinkat
 254 system calls first appeared in
 255 .Fx 12.1 .