| blob | 031c3f5ba897579749533e0e9c884bfc7116c34b |
1 .\" $NetBSD: link.2,v 1.26 2011/08/08 19:50:17 wiz 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 January 12, 1994
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 .Ft int
45 .Fn linkat "int fd1" "const char *name1" "int fd2" "const char *name2" "int flags"
46 .Sh DESCRIPTION
47 The
48 .Fn link
49 function call
50 atomically creates the specified directory entry (hard link)
51 .Fa name2
52 with the attributes of the underlying object pointed at by
53 .Fa name1 .
54 If the link is successful: the link count of the underlying object
55 is incremented;
56 .Fa name1
57 and
58 .Fa name2
59 share equal access and rights
60 to the
61 underlying object.
62 .Pp
63 If
64 .Fa name1
65 is removed, the file
66 .Fa name2
67 is not deleted and the link count of the
68 underlying object is
69 decremented.
70 .Pp
71 .Fa name1
72 must exist for the hard link to
73 succeed and
74 both
75 .Fa name1
76 and
77 .Fa name2
78 must be in the same file system.
79 .Fa name1
80 may not be a directory unless the caller is the super-user
81 and the file system containing it supports linking to directories.
82 .Pp
83 When operating on a symlink,
84 .Fn link
85 resolves the symlink and creates a hard link on the target.
86 .Fn linkat
87 will do the same if
88 .Dv AT_SYMLINK_FOLLOW
89 is set in
90 .Fa flags ,
91 but it will link on the symlink itself if the flag is clear.
92 .Pp
93 At the moment,
94 .Fn linkat
95 is partially implemented.
96 It will return
97 .Er ENOSYS
98 for
99 .Fa fd1
100 and
101 .Fa fd2
102 values different than
103 .Dv AT_FDCWD .
104 .Sh RETURN VALUES
105 Upon successful completion, a value of 0 is returned.
106 Otherwise, a value of \-1 is returned and
107 .Va errno
108 is set to indicate the error.
109 .Sh ERRORS
110 .Fn link
111 will fail and no link will be created if:
112 .Bl -tag -width Er
113 .It Bq Er EACCES
114 A component of either path prefix denies search permission, or
115 the requested link requires writing in a directory with a mode
116 that denies write permission.
117 .It Bq Er EDQUOT
118 The directory in which the entry for the new link
119 is being placed cannot be extended because the
120 user's quota of disk blocks on the file system
121 containing the directory has been exhausted.
122 .It Bq Er EEXIST
123 The link named by
124 .Fa name2
125 does exist.
126 .It Bq Er EFAULT
127 One of the pathnames specified
128 is outside the process's allocated address space.
129 .It Bq Er EIO
130 An I/O error occurred while reading from or writing to
131 the file system to make the directory entry.
132 .It Bq Er ELOOP
133 Too many symbolic links were encountered in translating one of the pathnames.
134 .It Bq Er EMLINK
135 The link count of the file named by
136 .Fa name1
137 would exceed
138 .Dv {LINK_MAX} .
139 .It Bq Er ENAMETOOLONG
140 A component of a pathname exceeded
141 .Brq Dv NAME_MAX
142 characters, or an entire path name exceeded
143 .Brq Dv PATH_MAX
144 characters.
145 .It Bq Er ENOENT
146 A component of either path prefix does not exist, or the file named
147 by
148 .Fa name1
149 does not exist.
150 .It Bq Er ENOSPC
151 The directory in which the entry for the new link is being placed
152 cannot be extended because there is no space left on the file
153 system containing the directory.
154 .It Bq Er ENOTDIR
155 A component of either path prefix is not a directory.
156 .It Bq Er EOPNOTSUPP
157 The file system containing the file named by
158 .Fa name1
159 does not support links.
160 .It Bq Er EPERM
161 The file named by
162 .Fa name1
163 is a directory and the effective
164 user ID is not super-user,
165 or the file system containing the file does not permit the use of
166 .Fn link
167 on a directory.
168 .It Bq Er EROFS
169 The requested link requires writing in a directory on a read-only file
170 system.
171 .It Bq Er EXDEV
172 The link named by
173 .Fa name2
174 and the file named by
175 .Fa name1
176 are on different file systems.
177 .El
178 .Sh SEE ALSO
179 .Xr symlink 2 ,
180 .Xr unlink 2
181 .Sh STANDARDS
182 The
183 .Fn link
184 function conforms to
185 .St -p1003.1-90 .
186 .Sh BUGS
187 .Fn linkat
188 is partially implemented.