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 November 29, 2018 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.El 117.Pp 118If 119.Fn fhlinkat 120is passed the special value 121.Dv AT_FDCWD 122in the 123.Fa tofd 124parameter, the current working directory is used for the 125.Fa to 126argument. 127If 128.Fa tofd 129has value 130.Dv AT_FDCWD , 131the behavior is identical to a call to 132.Fn link . 133Unless 134.Fa flag 135contains the 136.Dv AT_SYMLINK_FOLLOW 137flag, if 138.Fa fhp 139names a symbolic link, a new link is created for the symbolic link 140.Fa fhp 141and not its target. 142.Sh RETURN VALUES 143.Rv -std link 144.Sh ERRORS 145The 146.Fn fhlink 147system call 148will fail and no link will be created if: 149.Bl -tag -width Er 150.It Bq Er ENOTDIR 151A component of 152.Fa to 153prefix is not a directory. 154.It Bq Er ENAMETOOLONG 155A component of 156.Fa to 157exceeded 255 characters, 158or entire length of 159.Fa to 160name exceeded 1023 characters. 161.It Bq Er ENOENT 162A component of 163.Fa to 164prefix does not exist. 165.It Bq Er EOPNOTSUPP 166The file system containing the file pointed at by 167.Fa fhp 168does not support links. 169.It Bq Er EMLINK 170The link count of the file pointed at by 171.Fa fhp 172would exceed 32767. 173.It Bq Er EACCES 174A component of 175.Fa to 176prefix denies search permission. 177.It Bq Er EACCES 178The requested link requires writing in a directory with a mode 179that denies write permission. 180.It Bq Er ELOOP 181Too many symbolic links were encountered in translating one of the pathnames. 182.It Bq Er ENOENT 183The file pointed at by 184.Fa fhp 185does not exist. 186.It Bq Er EEXIST 187The link named by 188.Fa to 189does exist. 190.It Bq Er EPERM 191The file pointed at by 192.Fa fhp 193is a directory. 194.It Bq Er EPERM 195The file pointed at by 196.Fa fhp 197has its immutable or append-only flag set, see the 198.Xr chflags 2 199manual page for more information. 200.It Bq Er EPERM 201The parent directory of the file named by 202.Fa to 203has its immutable flag set. 204.It Bq Er EXDEV 205The link named by 206.Fa to 207and the file pointed at by 208.Fa fhp 209are on different file systems. 210.It Bq Er ENOSPC 211The directory in which the entry for the new link is being placed 212cannot be extended because there is no space left on the file 213system containing the directory. 214.It Bq Er EDQUOT 215The directory in which the entry for the new link 216is being placed cannot be extended because the 217user's quota of disk blocks on the file system 218containing the directory has been exhausted. 219.It Bq Er EIO 220An I/O error occurred while reading from or writing to 221the file system to make the directory entry. 222.It Bq Er EROFS 223The requested link requires writing in a directory on a read-only file 224system. 225.It Bq Er EFAULT 226One of the pathnames specified 227is outside the process's allocated address space. 228.It Bq Er ESTALE 229The file handle 230.Fa fhp 231is no longer valid 232.El 233.Pp 234In addition to the errors returned by the 235.Fn fhlink , 236the 237.Fn fhlinkat 238system call may fail if: 239.Bl -tag -width Er 240.It Bq Er EBADF 241The 242.Fa fhp 243or 244.Fa to 245argument does not specify an absolute path and the 246.Fa tofd 247argument, is not 248.Dv AT_FDCWD 249nor a valid file descriptor open for searching. 250.It Bq Er EINVAL 251The value of the 252.Fa flag 253argument is not valid. 254.It Bq Er ENOTDIR 255The 256.Fa fhp 257or 258.Fa to 259argument is not an absolute path and 260.Fa tofd 261is not 262.Dv AT_FDCWD 263nor a file descriptor associated with a directory. 264.El 265.Sh SEE ALSO 266.Xr fhstat 2 , 267.Xr fhreadlink 2 , 268.Xr fhopen 2 , 269