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