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