xref: /freebsd/lib/libsys/link.2 (revision 7fdf597e96a02165cfe22ff357b857d5fa15ed8a)
1.\" Copyright (c) 1980, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd March 30, 2021
29.Dt LINK 2
30.Os
31.Sh NAME
32.Nm link ,
33.Nm linkat
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 link "const char *name1" "const char *name2"
41.Ft int
42.Fo linkat
43.Fa "int fd1" "const char *name1" "int fd2" "const char *name2" "int flag"
44.Fc
45.Sh DESCRIPTION
46The
47.Fn link
48system call
49atomically creates the specified directory entry (hard link)
50.Fa name2
51with the attributes of the underlying object pointed at by
52.Fa name1 .
53If the link is successful: the link count of the underlying object
54is incremented;
55.Fa name1
56and
57.Fa name2
58share equal access and rights
59to the
60underlying object.
61.Pp
62If
63.Fa name1
64is removed, the file
65.Fa name2
66is not deleted and the link count of the
67underlying object is
68decremented.
69.Pp
70The object pointed at by the
71.Fa name1
72argument
73must exist for the hard link to
74succeed and
75both
76.Fa name1
77and
78.Fa name2
79must be in the same file system.
80The
81.Fa name1
82argument
83may not be a directory.
84.Pp
85The
86.Fn linkat
87system call is equivalent to
88.Fa link
89except in the case where either
90.Fa name1
91or
92.Fa name2
93or both are relative paths.
94In this case a relative path
95.Fa name1
96is interpreted relative to
97the directory associated with the file descriptor
98.Fa fd1
99instead of the current working directory and similarly for
100.Fa name2
101and the file descriptor
102.Fa fd2 .
103.Pp
104Values for
105.Fa flag
106are constructed by a bitwise-inclusive OR of flags from the following
107list, defined in
108.In fcntl.h :
109.Bl -tag -width indent
110.It Dv AT_SYMLINK_FOLLOW
111If
112.Fa name1
113names a symbolic link, a new link for the target of the symbolic link is
114created.
115.It Dv AT_RESOLVE_BENEATH
116Only walk paths below the directory specified by the
117.Ar fd1
118descriptor.
119See the description of the
120.Dv O_RESOLVE_BENEATH
121flag in the
122.Xr open 2
123manual page.
124.It Dv AT_EMPTY_PATH
125If the
126.Fa name1
127argument is an empty string, link the file referenced by the descriptor
128.Fa fd1 .
129The operation requires that the calling process has the
130.Dv PRIV_VFS_FHOPEN
131privilege, effectively being executed with effective user
132.Dv root .
133.El
134.Pp
135If
136.Fn linkat
137is passed the special value
138.Dv AT_FDCWD
139in the
140.Fa fd1
141or
142.Fa fd2
143parameter, the current working directory is used for the respective
144.Fa name
145argument.
146If both
147.Fa fd1
148and
149.Fa fd2
150have value
151.Dv AT_FDCWD ,
152the behavior is identical to a call to
153.Fn link .
154Unless
155.Fa flag
156contains the
157.Dv AT_SYMLINK_FOLLOW
158flag, if
159.Fa name1
160names a symbolic link, a new link is created for the symbolic link
161.Fa name1
162and not its target.
163.Sh RETURN VALUES
164.Rv -std link
165.Sh ERRORS
166The
167.Fn link
168system call
169will fail and no link will be created if:
170.Bl -tag -width Er
171.It Bq Er ENOTDIR
172A component of either path prefix is not a directory.
173.It Bq Er ENAMETOOLONG
174A component of either pathname exceeded 255 characters,
175or entire length of either path name exceeded 1023 characters.
176.It Bq Er ENOENT
177A component of either path prefix does not exist.
178.It Bq Er EOPNOTSUPP
179The file system containing the file named by
180.Fa name1
181does not support links.
182.It Bq Er EMLINK
183The link count of the file named by
184.Fa name1
185would exceed 32767.
186.It Bq Er EACCES
187A component of either path prefix denies search permission.
188.It Bq Er EACCES
189The requested link requires writing in a directory with a mode
190that denies write permission.
191.It Bq Er ELOOP
192Too many symbolic links were encountered in translating one of the pathnames.
193.It Bq Er ENOENT
194The file named by
195.Fa name1
196does not exist.
197.It Bq Er EEXIST
198The link named by
199.Fa name2
200does exist.
201.It Bq Er EPERM
202The file named by
203.Fa name1
204is a directory.
205.It Bq Er EPERM
206The file named by
207.Fa name1
208has its immutable or append-only flag set, see the
209.Xr chflags 2
210manual page for more information.
211.It Bq Er EPERM
212The parent directory of the file named by
213.Fa name2
214has its immutable flag set.
215.It Bq Er EXDEV
216The link named by
217.Fa name2
218and the file named by
219.Fa name1
220are on different file systems.
221.It Bq Er ENOSPC
222The directory in which the entry for the new link is being placed
223cannot be extended because there is no space left on the file
224system containing the directory.
225.It Bq Er EDQUOT
226The directory in which the entry for the new link
227is being placed cannot be extended because the
228user's quota of disk blocks on the file system
229containing the directory has been exhausted.
230.It Bq Er EIO
231An I/O error occurred while reading from or writing to
232the file system to make the directory entry.
233.It Bq Er EINTEGRITY
234Corrupted data was detected while reading from the file system.
235.It Bq Er EROFS
236The requested link requires writing in a directory on a read-only file
237system.
238.It Bq Er EFAULT
239One of the pathnames specified
240is outside the process's allocated address space.
241.El
242.Pp
243In addition to the errors returned by the
244.Fn link ,
245the
246.Fn linkat
247system call may fail if:
248.Bl -tag -width Er
249.It Bq Er EBADF
250The
251.Fa name1
252or
253.Fa name2
254argument does not specify an absolute path and the
255.Fa fd1
256or
257.Fa fd2
258argument, respectively, is neither
259.Dv AT_FDCWD
260nor a valid file descriptor open for searching.
261.It Bq Er EINVAL
262The value of the
263.Fa flag
264argument is not valid.
265.It Bq Er ENOTDIR
266The
267.Fa name1
268or
269.Fa name2
270argument is not an absolute path and
271.Fa fd1
272or
273.Fa fd2 ,
274respectively, is neither
275.Dv AT_FDCWD
276nor a file descriptor associated with a directory.
277.It Bq Er ENOTCAPABLE
278.Fa name1
279is not strictly relative to the starting directory.
280For example,
281.Fa name1
282is absolute or includes a ".." component that escapes
283the directory hierarchy specified by
284.Fa fd ,
285and the process is in capability mode or the
286.Dv AT_RESOLVE_BENEATH
287flag was specified.
288.El
289.Sh SEE ALSO
290.Xr chflags 2 ,
291.Xr readlink 2 ,
292.Xr symlink 2 ,
293.Xr unlink 2
294.Sh STANDARDS
295The
296.Fn link
297system call is expected to conform to
298.St -p1003.1-90 .
299The
300.Fn linkat
301system call follows The Open Group Extended API Set 2 specification.
302.Sh HISTORY
303The
304.Fn link
305function appeared in
306.At v1 .
307The
308.Fn linkat
309system call appeared in
310.Fx 8.0 .
311.Pp
312The
313.Fn link
314system call traditionally allows the super-user to link directories which
315corrupts the file system coherency.
316This implementation no longer permits it.
317