]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man2/symlink.2
xnu-2782.30.5.tar.gz
[apple/xnu.git] / bsd / man / man2 / symlink.2
1 .\" $NetBSD: symlink.2,v 1.7 1995/02/27 12:38:34 cgd Exp $
2 .\"
3 .\" Copyright (c) 1983, 1991, 1993
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. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgement:
16 .\" This product includes software developed by the University of
17 .\" California, Berkeley and its contributors.
18 .\" 4. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\"
34 .\" @(#)symlink.2 8.1 (Berkeley) 6/4/93
35 .\"
36 .Dd June 4, 1993
37 .Dt SYMLINK 2
38 .Os BSD 4.2
39 .Sh NAME
40 .Nm symlink ,
41 .Nm symlinkat
42 .Nd make symbolic link to a file
43 .Sh SYNOPSIS
44 .Fd #include <unistd.h>
45 .Ft int
46 .Fo symlink
47 .Fa "const char *path1"
48 .Fa "const char *path2"
49 .Fc
50 .Ft int
51 .Fn symlinkat "const char *name1" "int fd" "const char *name2"
52 .Sh DESCRIPTION
53 A symbolic link
54 .Fa path2
55 is created to
56 .Fa path1
57 .Pf ( Fa path2
58 is the name of the
59 file created,
60 .Fa path1
61 is the string
62 used in creating the symbolic link).
63 Either name may be an arbitrary path name; the files need not
64 be on the same file system.
65 .Pp
66 The
67 .Fn symlinkat
68 system call is equivalent to
69 .Fn symlink
70 except in the case where
71 .Fa name2
72 specifies a relative path.
73 In this case the symbolic link is created relative to the directory
74 associated with the file descriptor
75 .Fa fd
76 instead of the current working directory.
77 If
78 .Fn symlinkat
79 is passed the special value
80 .Dv AT_FDCWD
81 in the
82 .Fa fd
83 parameter, the current working directory is used and the behavior is
84 identical to a call to
85 .Fn symlink .
86 .Sh RETURN VALUES
87 Upon successful completion, a zero value is returned.
88 If an error occurs, the error code is stored in
89 .Va errno
90 and a -1 value is returned.
91 .Sh ERRORS
92 The symbolic link succeeds unless:
93 .Bl -tag -width Er
94 .\" ===========
95 .It Bq Er EACCES
96 Write permission is denied in the directory
97 where the symbolic link is being created.
98 .\" ===========
99 .It Bq Er EACCES
100 A component of the
101 .Fa path2
102 path prefix denies search permission.
103 .\" ===========
104 .It Bq Er EDQUOT
105 The directory in which the entry for the new symbolic link
106 is being placed cannot be extended because the
107 user's quota of disk blocks on the file system
108 containing the directory has been exhausted.
109 .\" ===========
110 .It Bq Er EDQUOT
111 The new symbolic link cannot be created because the user's
112 quota of disk blocks on the file system that will
113 contain the symbolic link has been exhausted.
114 .\" ===========
115 .It Bq Er EDQUOT
116 The user's quota of inodes on the file system on
117 which the symbolic link is being created has been exhausted.
118 .\" ===========
119 .It Bq Er EEXIST
120 .Fa Path2
121 already exists.
122 .\" ===========
123 .It Bq Er EFAULT
124 .Fa Path1
125 or
126 .Fa path2
127 points outside the process's allocated address space.
128 .\" ===========
129 .It Bq Er EIO
130 An I/O error occurs while making the directory entry
131 or allocating the inode.
132 .\" ===========
133 .It Bq Er EIO
134 An I/O error occurs while making the directory entry for
135 .Fa path2 ,
136 or allocating the inode for
137 .Fa path2 ,
138 or writing out the link contents of
139 .Fa path2 .
140 .\" ===========
141 .It Bq Er ELOOP
142 Too many symbolic links are encountered in translating the pathname.
143 This is taken to be indicative of a looping symbolic link.
144 .\" ===========
145 .It Bq Er ENAMETOOLONG
146 A component of a pathname exceeds
147 .Dv {NAME_MAX}
148 characters, or an entire path name exceeds
149 .Dv {PATH_MAX}
150 characters.
151 .\" ===========
152 .It Bq Er ENOENT
153 A component of
154 .Fa path2
155 does not name an existing file or
156 .Fa path2
157 is an empty string.
158 .\" ===========
159 .It Bq Er ENOSPC
160 The directory in which the entry for the new symbolic link is being placed
161 cannot be extended because there is no space left on the file
162 system containing the directory.
163 .\" ===========
164 .It Bq Er ENOSPC
165 The new symbolic link cannot be created because there
166 there is no space left on the file
167 system that will contain the symbolic link.
168 .\" ===========
169 .It Bq Er ENOSPC
170 There are no free inodes on the file system on which the
171 symbolic link is being created.
172 .\" ===========
173 .It Bq Er ENOTDIR
174 A component of the
175 .Fa path2
176 prefix is not a directory.
177 .\" ===========
178 .It Bq Er EROFS
179 The file
180 .Fa path2
181 would reside on a read-only file system.
182 .El
183 .Pp
184 In addition to the errors returned by the
185 .Fn symlink ,
186 the
187 .Fn symlinkat
188 may fail if:
189 .Bl -tag -width Er
190 .It Bq Er EBADF
191 The
192 .Fa name2
193 argument does not specify an absolute path and the
194 .Fa fd
195 argument is neither
196 .Dv AT_FDCWD
197 nor a valid file descriptor open for searching.
198 .It Bq Er ENOTDIR
199 The
200 .Fa name2
201 argument is not an absolute path and
202 .Fa fd
203 is neither
204 .Dv AT_FDCWD
205 nor a file descriptor associated with a directory.
206 .El
207 .Sh SEE ALSO
208 .Xr ln 1 ,
209 .Xr link 2 ,
210 .Xr unlink 2 ,
211 .Xr symlink 7
212 .Sh STANDARDS
213 The
214 .Fn symlinkat
215 system call is expected to conform to POSIX.1-2008 .
216 .Sh HISTORY
217 The
218 .Fn symlink
219 function call appeared in
220 .Bx 4.2 .
221 The
222 .Fn symlinkat
223 system call appeared in OS X 10.10