link.2: Use .Fn and add .Nm linkat
[dragonfly.git] / lib / libc / sys / link.2
CommitLineData
984263bc
MD
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. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)link.2 8.3 (Berkeley) 1/12/94
33.\" $FreeBSD: src/lib/libc/sys/link.2,v 1.11.2.7 2001/12/14 18:34:01 ru Exp $
34.\"
34e96d8c 35.Dd July 31, 2012
984263bc
MD
36.Dt LINK 2
37.Os
38.Sh NAME
ac5242c1
SW
39.Nm link ,
40.Nm linkat
984263bc
MD
41.Nd make a hard file link
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In unistd.h
46.Ft int
47.Fn link "const char *name1" "const char *name2"
34e96d8c
AH
48.Ft int
49.Fn linkat "int fd1" "const char *name1" "int fd2" "const char *name2" "int flags"
984263bc
MD
50.Sh DESCRIPTION
51The
52.Fn link
53function call
54atomically creates the specified directory entry (hard link)
55.Fa name2
56with the attributes of the underlying object pointed at by
57.Fa name1 .
58If the link is successful: the link count of the underlying object
59is incremented;
60.Fa name1
61and
62.Fa name2
63share equal access and rights
64to the
65underlying object.
66.Pp
67If
68.Fa name1
69is removed, the file
70.Fa name2
71is not deleted and the link count of the
72underlying object is
73decremented.
74.Pp
75.Fa Name1
76must exist for the hard link to
77succeed and
78both
79.Fa name1
80and
81.Fa name2
82must be in the same file system.
83.Fa name1
84may not be a directory.
34e96d8c
AH
85.Pp
86When operating on a symlink,
87.Fn link
88resolves the symlink and creates a hard link on the target.
89.Fn linkat
90will do the same if
91.Dv AT_SYMLINK_FOLLOW
92is set in
93.Fa flags ,
94but it will link on the symlink itself if the flag is clear.
95.Pp
96The
97.Fn linkat
98system call is equivalent to
ac5242c1 99.Fn link
34e96d8c
AH
100except in the case where either
101.Fa name1
102or
103.Fa name2
104or both are relative paths.
105In this case a relative path
106.Fa name1
107is interpreted relative to the directory associated with the file descriptor
108.Fa fd1
109instead of the current working directory and similarly for
110.Fa name2
111and the file descriptor
112.Fa fd2 .
113If
114.Fa fd1
115or
116.Fa fd2
117has the special value
118.Dv AT_FDCWD
119then
120.Fa name1
121or
122.Fa name2
123respectively is interpreted relative to the current working directory.
984263bc
MD
124.Sh RETURN VALUES
125.Rv -std link
126.Sh ERRORS
127.Fn Link
128will fail and no link will be created if:
129.Bl -tag -width Er
130.It Bq Er ENOTDIR
131A component of either path prefix is not a directory.
132.It Bq Er ENAMETOOLONG
133A component of either pathname exceeded 255 characters,
134or entire length of either path name exceeded 1023 characters.
135.It Bq Er ENOENT
136A component of either path prefix does not exist.
137.It Bq Er EOPNOTSUPP
138The file system containing the file named by
139.Fa name1
140does not support links.
141.It Bq Er EMLINK
142The link count of the file named by
143.Fa name1
144would exceed 32767.
145.It Bq Er EACCES
146A component of either path prefix denies search permission.
147.It Bq Er EACCES
148The requested link requires writing in a directory with a mode
149that denies write permission.
150.It Bq Er ELOOP
151Too many symbolic links were encountered in translating one of the pathnames.
152.It Bq Er ENOENT
153The file named by
154.Fa name1
155does not exist.
156.It Bq Er EEXIST
157The link named by
158.Fa name2
159does exist.
160.It Bq Er EPERM
a009fae0
SW
161The named file has its immutable or append-only flag set (see
162.Xr chflags 2 ) .
85f90be2 163.It Bq Er EPERM
984263bc
MD
164The file named by
165.Fa name1
166is a directory.
167.It Bq Er EXDEV
168The link named by
169.Fa name2
170and the file named by
171.Fa name1
172are on different file systems.
173.It Bq Er ENOSPC
174The directory in which the entry for the new link is being placed
175cannot be extended because there is no space left on the file
176system containing the directory.
177.It Bq Er EDQUOT
178The directory in which the entry for the new link
179is being placed cannot be extended because the
180user's quota of disk blocks on the file system
181containing the directory has been exhausted.
182.It Bq Er EIO
183An I/O error occurred while reading from or writing to
184the file system to make the directory entry.
185.It Bq Er EROFS
186The requested link requires writing in a directory on a read-only file
187system.
188.It Bq Er EFAULT
189One of the pathnames specified
190is outside the process's allocated address space.
191.El
34e96d8c
AH
192.Pp
193In addition to the errors returned by the
194.Fn link
195syscall, the
196.Fn linkat
197system call may fail if:
198.Bl -tag -width Er
199.It Bq Er EBADF
200The
201.Fa name1
202or
203.Fa name2
204argument does not specify an absolute path and the
205.Fa fd1
206or
207.Fa fd2
208argument, respectively, is neither
209.Dv AT_FDCWD
210nor a valid file descriptor open for searching.
211.It Bq Er ENOTDIR
212The
213.Fa name1
214or
215.Fa name2
216argument is not an absolute path and
217.Fa fd1
218or
219.Fa fd2 ,
220respectively, is neither
221.Dv AT_FDCWD
222nor a file descriptor associated with a directory.
223.El
984263bc
MD
224.Sh SEE ALSO
225.Xr readlink 2 ,
226.Xr symlink 2 ,
227.Xr unlink 2
228.Sh STANDARDS
229The
230.Fn link
231function call is expected to conform to
232.St -p1003.1-90 .
233.Sh HISTORY
234A
235.Fn link
236function call appeared in
237.At v7 .
34e96d8c
AH
238The
239.Fn linkat
240system call appeared in
241.Dx 3.1 .
984263bc
MD
242.Pp
243The
244.Fn link
245system call traditionally allows the super-user to link directories which
246corrupts the filesystem coherency. This implementation no longer permits
247it.