Sun Sep 1 19:52:32 2019 UTC ()
Document history
https://www.bell-labs.com/usr/dmr/www/man21.pdf


(sevan)
diff -r1.32 -r1.33 src/lib/libc/sys/link.2
cvs diff -r1.32 -r1.33 src/lib/libc/sys/link.2 (switch to unified diff)

--- src/lib/libc/sys/link.2 2013/07/28 18:40:40 1.32
+++ src/lib/libc/sys/link.2 2019/09/01 19:52:32 1.33
@@ -1,242 +1,247 @@ @@ -1,242 +1,247 @@
1.\" $NetBSD: link.2,v 1.32 2013/07/28 18:40:40 njoly Exp $ 1.\" $NetBSD: link.2,v 1.33 2019/09/01 19:52:32 sevan Exp $
2.\" 2.\"
3.\" Copyright (c) 1980, 1991, 1993, 2011 3.\" Copyright (c) 1980, 1991, 1993, 2011
4.\" The Regents of the University of California. All rights reserved. 4.\" The Regents of the University of California. All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors 14.\" 3. Neither the name of the University nor the names of its contributors
15.\" may be used to endorse or promote products derived from this software 15.\" may be used to endorse or promote products derived from this software
16.\" without specific prior written permission. 16.\" without specific prior written permission.
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE. 28.\" SUCH DAMAGE.
29.\" 29.\"
30.\" @(#)link.2 8.3 (Berkeley) 1/12/94 30.\" @(#)link.2 8.3 (Berkeley) 1/12/94
31.\" 31.\"
32.Dd July 28, 2013 32.Dd September 1, 2019
33.Dt LINK 2 33.Dt LINK 2
34.Os 34.Os
35.Sh NAME 35.Sh NAME
36.Nm link 36.Nm link
37.Nd make a hard file link 37.Nd make a hard file link
38.Sh LIBRARY 38.Sh LIBRARY
39.Lb libc 39.Lb libc
40.Sh SYNOPSIS 40.Sh SYNOPSIS
41.In unistd.h 41.In unistd.h
42.Ft int 42.Ft int
43.Fn link "const char *name1" "const char *name2" 43.Fn link "const char *name1" "const char *name2"
44.In fcntl.h 44.In fcntl.h
45.Ft int 45.Ft int
46.Fn linkat "int fd1" "const char *name1" "int fd2" "const char *name2" "int flags" 46.Fn linkat "int fd1" "const char *name1" "int fd2" "const char *name2" "int flags"
47.Sh DESCRIPTION 47.Sh DESCRIPTION
48The 48The
49.Fn link 49.Fn link
50function call 50function call
51atomically creates the specified directory entry (hard link) 51atomically creates the specified directory entry (hard link)
52.Fa name2 52.Fa name2
53with the attributes of the underlying object pointed at by 53with the attributes of the underlying object pointed at by
54.Fa name1 . 54.Fa name1 .
55If the link is successful: the link count of the underlying object 55If the link is successful: the link count of the underlying object
56is incremented; 56is incremented;
57.Fa name1 57.Fa name1
58and 58and
59.Fa name2 59.Fa name2
60share equal access and rights 60share equal access and rights
61to the 61to the
62underlying object. 62underlying object.
63.Pp 63.Pp
64If 64If
65.Fa name1 65.Fa name1
66is removed, the file 66is removed, the file
67.Fa name2 67.Fa name2
68is not deleted and the link count of the 68is not deleted and the link count of the
69underlying object is 69underlying object is
70decremented. 70decremented.
71.Pp 71.Pp
72.Fa name1 72.Fa name1
73must exist for the hard link to 73must exist for the hard link to
74succeed and 74succeed and
75both 75both
76.Fa name1 76.Fa name1
77and 77and
78.Fa name2 78.Fa name2
79must be in the same file system. 79must be in the same file system.
80.Fa name1 80.Fa name1
81may not be a directory unless the caller is the super-user 81may not be a directory unless the caller is the super-user
82and the file system containing it supports linking to directories. 82and the file system containing it supports linking to directories.
83.Pp 83.Pp
84.Fn linkat 84.Fn linkat
85works the same way as 85works the same way as
86.Fn link 86.Fn link
87except if 87except if
88.Fa name1 88.Fa name1
89(resp. 89(resp.
90.Fa name2 ) 90.Fa name2 )
91is relative. 91is relative.
92In that case, it is looked up from a directory whose file 92In that case, it is looked up from a directory whose file
93descriptor was passed as 93descriptor was passed as
94.Fa fd1 94.Fa fd1
95(resp. 95(resp.
96.Fa fd2 ) . 96.Fa fd2 ) .
97Search permission is required on the directories named by 97Search permission is required on the directories named by
98.Fa fd1 98.Fa fd1
99and 99and
100.Fa fd2 . 100.Fa fd2 .
101.\" (These alternatives await a decision about the semantics of O_SEARCH) 101.\" (These alternatives await a decision about the semantics of O_SEARCH)
102.\" Search permission is required on the directories named by 102.\" Search permission is required on the directories named by
103.\" .Fa fd1 103.\" .Fa fd1
104.\" and 104.\" and
105.\" .Fa fd2 105.\" .Fa fd2
106.\" unless they were opened with the 106.\" unless they were opened with the
107.\" .Dv O_SEARCH 107.\" .Dv O_SEARCH
108.\" flag. 108.\" flag.
109.\" - or - 109.\" - or -
110.\" The directories named by 110.\" The directories named by
111.\" .Fa fd1 111.\" .Fa fd1
112.\" and 112.\" and
113.\" .Fa fd2 113.\" .Fa fd2
114.\" must have been opened with the 114.\" must have been opened with the
115.\" .Dv O_SEARCH 115.\" .Dv O_SEARCH
116.\" flag. 116.\" flag.
117.Fa fd1 117.Fa fd1
118or 118or
119.Fa fd2 119.Fa fd2
120can be set to 120can be set to
121.Dv AT_FDCWD 121.Dv AT_FDCWD
122in order to specify the current directory. 122in order to specify the current directory.
123.Pp 123.Pp
124When operating on a symlink, 124When operating on a symlink,
125.Fn link 125.Fn link
126resolves the symlink and creates a hard link on the target. 126resolves the symlink and creates a hard link on the target.
127.Fn linkat 127.Fn linkat
128will do the same if 128will do the same if
129.Dv AT_SYMLINK_FOLLOW 129.Dv AT_SYMLINK_FOLLOW
130is set in 130is set in
131.Fa flags , 131.Fa flags ,
132but it will link on the symlink itself if the flag is clear. 132but it will link on the symlink itself if the flag is clear.
133.Sh RETURN VALUES 133.Sh RETURN VALUES
134.Rv -std link linkat 134.Rv -std link linkat
135.Sh ERRORS 135.Sh ERRORS
136.Fn link 136.Fn link
137and 137and
138.Fn linkat 138.Fn linkat
139will fail and no link will be created if: 139will fail and no link will be created if:
140.Bl -tag -width Er 140.Bl -tag -width Er
141.It Bq Er EACCES 141.It Bq Er EACCES
142A component of either path prefix denies search permission, or 142A component of either path prefix denies search permission, or
143the requested link requires writing in a directory with a mode 143the requested link requires writing in a directory with a mode
144that denies write permission. 144that denies write permission.
145.It Bq Er EDQUOT 145.It Bq Er EDQUOT
146The directory in which the entry for the new link 146The directory in which the entry for the new link
147is being placed cannot be extended because the 147is being placed cannot be extended because the
148user's quota of disk blocks on the file system 148user's quota of disk blocks on the file system
149containing the directory has been exhausted. 149containing the directory has been exhausted.
150.It Bq Er EEXIST 150.It Bq Er EEXIST
151The link named by 151The link named by
152.Fa name2 152.Fa name2
153does exist. 153does exist.
154.It Bq Er EFAULT 154.It Bq Er EFAULT
155One of the pathnames specified 155One of the pathnames specified
156is outside the process's allocated address space. 156is outside the process's allocated address space.
157.It Bq Er EIO 157.It Bq Er EIO
158An I/O error occurred while reading from or writing to 158An I/O error occurred while reading from or writing to
159the file system to make the directory entry. 159the file system to make the directory entry.
160.It Bq Er ELOOP 160.It Bq Er ELOOP
161Too many symbolic links were encountered in translating one of the pathnames. 161Too many symbolic links were encountered in translating one of the pathnames.
162.It Bq Er EMLINK 162.It Bq Er EMLINK
163The link count of the file named by 163The link count of the file named by
164.Fa name1 164.Fa name1
165would exceed 165would exceed
166.Brq Dv LINK_MAX . 166.Brq Dv LINK_MAX .
167.It Bq Er ENAMETOOLONG 167.It Bq Er ENAMETOOLONG
168A component of a pathname exceeded 168A component of a pathname exceeded
169.Brq Dv NAME_MAX 169.Brq Dv NAME_MAX
170characters, or an entire path name exceeded 170characters, or an entire path name exceeded
171.Brq Dv PATH_MAX 171.Brq Dv PATH_MAX
172characters. 172characters.
173.It Bq Er ENOENT 173.It Bq Er ENOENT
174A component of either path prefix does not exist, or the file named 174A component of either path prefix does not exist, or the file named
175by 175by
176.Fa name1 176.Fa name1
177does not exist. 177does not exist.
178.It Bq Er ENOSPC 178.It Bq Er ENOSPC
179The directory in which the entry for the new link is being placed 179The directory in which the entry for the new link is being placed
180cannot be extended because there is no space left on the file 180cannot be extended because there is no space left on the file
181system containing the directory. 181system containing the directory.
182.It Bq Er ENOTDIR 182.It Bq Er ENOTDIR
183A component of either path prefix is not a directory. 183A component of either path prefix is not a directory.
184.It Bq Er EOPNOTSUPP 184.It Bq Er EOPNOTSUPP
185The file system containing the file named by 185The file system containing the file named by
186.Fa name1 186.Fa name1
187does not support links. 187does not support links.
188.It Bq Er EPERM 188.It Bq Er EPERM
189The file named by 189The file named by
190.Fa name1 190.Fa name1
191is a directory and the effective 191is a directory and the effective
192user ID is not super-user, 192user ID is not super-user,
193or the file system containing the file does not permit the use of 193or the file system containing the file does not permit the use of
194.Fn link 194.Fn link
195on a directory. 195on a directory.
196.It Bq Er EROFS 196.It Bq Er EROFS
197The requested link requires writing in a directory on a read-only file 197The requested link requires writing in a directory on a read-only file
198system. 198system.
199.It Bq Er EXDEV 199.It Bq Er EXDEV
200The link named by 200The link named by
201.Fa name2 201.Fa name2
202and the file named by 202and the file named by
203.Fa name1 203.Fa name1
204are on different file systems. 204are on different file systems.
205.El 205.El
206.Pp 206.Pp
207In addition, 207In addition,
208.Fn linkat 208.Fn linkat
209will fail if: 209will fail if:
210.Bl -tag -width Er 210.Bl -tag -width Er
211.It Bq Er EBADF 211.It Bq Er EBADF
212.Fa name1 212.Fa name1
213or 213or
214.Fa name2 214.Fa name2
215does not specify an absolute path and 215does not specify an absolute path and
216.Fa fd1 216.Fa fd1
217or 217or
218.Fa fd2 , 218.Fa fd2 ,
219respectively, is neither 219respectively, is neither
220.Dv AT_FDCWD 220.Dv AT_FDCWD
221nor a valid file descriptor open for reading or searching. 221nor a valid file descriptor open for reading or searching.
222.It Bq Er ENOTDIR 222.It Bq Er ENOTDIR
223.Fa name1 223.Fa name1
224or 224or
225.Fa name2 225.Fa name2
226is not an absolute path and 226is not an absolute path and
227.Fa fd1 227.Fa fd1
228or 228or
229.Fa fd2 , 229.Fa fd2 ,
230respectively, is a file descriptor associated with a non-directory file. 230respectively, is a file descriptor associated with a non-directory file.
231.El 231.El
232.Sh SEE ALSO 232.Sh SEE ALSO
233.Xr symlink 2 , 233.Xr symlink 2 ,
234.Xr unlink 2 234.Xr unlink 2
235.Sh STANDARDS 235.Sh STANDARDS
236The 236The
237.Fn link 237.Fn link
238function conforms to 238function conforms to
239.St -p1003.1-90 . 239.St -p1003.1-90 .
240.Fn linkat 240.Fn linkat
241conforms to 241conforms to
242.St -p1003.1-2008 . 242.St -p1003.1-2008 .
 243.Sh HISTORY
 244The
 245.Fn link
 246function appeared in
 247.At v1 .