Debian Codegraph @

upstream/debian-unstable/man2/symlink.2

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