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