Debian Codegraph @

upstream/debian-trixie/man2/symlink.2

raw
1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
2 .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
3 .\" and Copyright (C) 2006, 2014 Michael Kerrisk
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" Modified 1993-07-24 by Rik Faith
8 .\" Modified 1996-04-26 by Nick Duffek <[email protected]>
9 .\" Modified 1996-11-06 by Eric S. Raymond <[email protected]>
10 .\" Modified 1997-01-31 by Eric S. Raymond <[email protected]>
11 .\" Modified 2004-06-23 by Michael Kerrisk <[email protected]>
12 .\"
13 .TH symlink 2 2024-05-02 "Linux man-pages 6.9.1"
14 .SH NAME
15 symlink, symlinkat \- make a new name for a file
16 .SH LIBRARY
17 Standard C library
18 .RI ( libc ", " \-lc )
19 .SH SYNOPSIS
20 .nf
21 .B #include <unistd.h>
22 .P
23 .BI "int symlink(const char *" target ", const char *" linkpath );
24 .P
25 .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
26 .B #include <unistd.h>
27 .P
28 .BI "int symlinkat(const char *" target ", int " newdirfd \
29 ", const char *" linkpath );
30 .P
31 .fi
32 .RS -4
33 Feature Test Macro Requirements for glibc (see
34 .BR feature_test_macros (7)):
35 .RE
36 .P
37 .BR symlink ():
38 .nf
39 _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
40 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
41 || /* glibc <= 2.19: */ _BSD_SOURCE
42 .fi
43 .P
44 .BR symlinkat ():
45 .nf
46 Since glibc 2.10:
47 _POSIX_C_SOURCE >= 200809L
48 Before glibc 2.10:
49 _ATFILE_SOURCE
50 .fi
51 .SH DESCRIPTION
52 .BR symlink ()
53 creates a symbolic link named
54 .I linkpath
55 which contains the string
56 .IR target .
57 .P
58 Symbolic links are interpreted at run time as if the contents of the
59 link had been substituted into the path being followed to find a file or
60 directory.
61 .P
62 Symbolic links may contain
63 .I ..
64 path components, which (if used at the start of the link) refer to the
65 parent directories of that in which the link resides.
66 .P
67 A symbolic link (also known as a soft link) may point to an existing
68 file or to a nonexistent one; the latter case is known as a dangling
69 link.
70 .P
71 The permissions of a symbolic link are irrelevant; the ownership is
72 ignored when following the link
73 (except when the
74 .I protected_symlinks
75 feature is enabled, as explained in
76 .BR proc (5)),
77 but is checked when removal or
78 renaming of the link is requested and the link is in a directory with
79 the sticky bit
80 .RB ( S_ISVTX )
81 set.
82 .P
83 If
84 .I linkpath
85 exists, it will
86 .I not
87 be overwritten.
88 .SS symlinkat()
89 The
90 .BR symlinkat ()
91 system call operates in exactly the same way as
92 .BR symlink (),
93 except for the differences described here.
94 .P
95 If the pathname given in
96 .I linkpath
97 is relative, then it is interpreted relative to the directory
98 referred to by the file descriptor
99 .I newdirfd
100 (rather than relative to the current working directory of
101 the calling process, as is done by
102 .BR symlink ()
103 for a relative pathname).
104 .P
105 If
106 .I linkpath
107 is relative and
108 .I newdirfd
109 is the special value
110 .BR AT_FDCWD ,
111 then
112 .I linkpath
113 is interpreted relative to the current working
114 directory of the calling process (like
115 .BR symlink ()).
116 .P
117 If
118 .I linkpath
119 is absolute, then
120 .I newdirfd
121 is ignored.
122 .P
123 See
124 .BR openat (2)
125 for an explanation of the need for
126 .BR symlinkat ().
127 .SH RETURN VALUE
128 On success, zero is returned.
129 On error, \-1 is returned, and
130 .I errno
131 is set to indicate the error.
132 .SH ERRORS
133 .TP
134 .B EACCES
135 Write access to the directory containing
136 .I linkpath
137 is denied, or one of the directories in the path prefix of
138 .I linkpath
139 did not allow search permission.
140 (See also
141 .BR path_resolution (7).)
142 .TP
143 .B EBADF
144 .RB ( symlinkat ())
145 .I linkpath
146 is relative but
147 .I newdirfd
148 is neither
149 .B AT_FDCWD
150 nor a valid file descriptor.
151 .TP
152 .B EDQUOT
153 The user's quota of resources on the filesystem has been exhausted.
154 The resources could be inodes or disk blocks, depending on the filesystem
155 implementation.
156 .TP
157 .B EEXIST
158 .I linkpath
159 already exists.
160 .TP
161 .B EFAULT
162 .IR target " or " linkpath " points outside your accessible address space."
163 .TP
164 .B EIO
165 An I/O error occurred.
166 .TP
167 .B ELOOP
168 Too many symbolic links were encountered in resolving
169 .IR linkpath .
170 .TP
171 .B ENAMETOOLONG
172 .IR target " or " linkpath " was too long."
173 .TP
174 .B ENOENT
175 A directory component in
176 .I linkpath
177 does not exist or is a dangling symbolic link, or
178 .I target
179 or
180 .I linkpath
181 is an empty string.
182 .TP
183 .B ENOENT
184 .RB ( symlinkat ())
185 .I linkpath
186 is a relative pathname and
187 .I newdirfd
188 refers to a directory that has been deleted.
189 .TP
190 .B ENOMEM
191 Insufficient kernel memory was available.
192 .TP
193 .B ENOSPC
194 The device containing the file has no room for the new directory
195 entry.
196 .TP
197 .B ENOTDIR
198 A component used as a directory in
199 .I linkpath
200 is not, in fact, a directory.
201 .TP
202 .B ENOTDIR
203 .RB ( symlinkat ())
204 .I linkpath
205 is relative and
206 .I newdirfd
207 is a file descriptor referring to a file other than a directory.
208 .TP
209 .B EPERM
210 The filesystem containing
211 .I linkpath
212 does not support the creation of symbolic links.
213 .TP
214 .B EROFS
215 .I linkpath
216 is on a read-only filesystem.
217 .SH STANDARDS
218 POSIX.1-2008.
219 .SH HISTORY
220 .TP
221 .BR symlink ()
222 SVr4, 4.3BSD, POSIX.1-2001.
223 .\" SVr4 documents additional error codes EDQUOT and ENOSYS.
224 .\" See
225 .\" .BR open (2)
226 .\" re multiple files with the same name, and NFS.
227 .TP
228 .BR symlinkat ()
229 POSIX.1-2008.
230 Linux 2.6.16,
231 glibc 2.4.
232 .SS glibc notes
233 On older kernels where
234 .BR symlinkat ()
235 is unavailable, the glibc wrapper function falls back to the use of
236 .BR symlink ().
237 When
238 .I linkpath
239 is a relative pathname,
240 glibc constructs a pathname based on the symbolic link in
241 .I /proc/self/fd
242 that corresponds to the
243 .I newdirfd
244 argument.
245 .SH NOTES
246 No checking of
247 .I target
248 is done.
249 .P
250 Deleting the name referred to by a symbolic link will actually delete the
251 file (unless it also has other hard links).
252 If this behavior is not desired, use
253 .BR link (2).
254 .SH SEE ALSO
255 .BR ln (1),
256 .BR namei (1),
257 .BR lchown (2),
258 .BR link (2),
259 .BR lstat (2),
260 .BR open (2),
261 .BR readlink (2),
262 .BR rename (2),
263 .BR unlink (2),
264 .BR path_resolution (7),
265 .BR symlink (7)