symlinkat(2)

1symlink(2)                    System Calls Manual                   symlink(2)
2
3
4

NAME

6       symlink, symlinkat - make a new name for a file
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <unistd.h>
13
14       int symlink(const char *target, const char *linkpath);
15
16       #include <fcntl.h>           /* Definition of AT_* constants */
17       #include <unistd.h>
18
19       int symlinkat(const char *target, int newdirfd, const char *linkpath);
20
21   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22
23       symlink():
24           _XOPEN_SOURCE >= 500 || _POSIX_C_SOURCE >= 200112L
25               || /* glibc <= 2.19: */ _BSD_SOURCE
26
27       symlinkat():
28           Since glibc 2.10:
29               _POSIX_C_SOURCE >= 200809L
30           Before glibc 2.10:
31               _ATFILE_SOURCE
32

DESCRIPTION

34       symlink()  creates  a  symbolic  link named linkpath which contains the
35       string target.
36
37       Symbolic links are interpreted at run time as if the  contents  of  the
38       link  had  been substituted into the path being followed to find a file
39       or directory.
40
41       Symbolic links may contain ..  path components, which (if used  at  the
42       start of the link) refer to the parent directories of that in which the
43       link resides.
44
45       A symbolic link (also known as a soft link) may point  to  an  existing
46       file  or  to  a nonexistent one; the latter case is known as a dangling
47       link.
48
49       The permissions of a symbolic link are irrelevant; the ownership is ig‐
50       nored  when following the link (except when the protected_symlinks fea‐
51       ture is enabled, as explained in proc(5)), but is checked when  removal
52       or  renaming  of  the  link is requested and the link is in a directory
53       with the sticky bit (S_ISVTX) set.
54
55       If linkpath exists, it will not be overwritten.
56
57   symlinkat()
58       The symlinkat() system call operates in exactly the same  way  as  sym‐
59       link(), except for the differences described here.
60
61       If  the  pathname given in linkpath is relative, then it is interpreted
62       relative to the directory referred to by the file  descriptor  newdirfd
63       (rather  than  relative to the current working directory of the calling
64       process, as is done by symlink() for a relative pathname).
65
66       If linkpath is relative and newdirfd is  the  special  value  AT_FDCWD,
67       then  linkpath is interpreted relative to the current working directory
68       of the calling process (like symlink()).
69
70       If linkpath is absolute, then newdirfd is ignored.
71
72       See openat(2) for an explanation of the need for symlinkat().
73

RETURN VALUE

75       On success, zero is returned.  On error, -1 is returned, and  errno  is
76       set to indicate the error.
77

ERRORS

79       EACCES Write  access to the directory containing linkpath is denied, or
80              one of the directories in the path prefix of  linkpath  did  not
81              allow search permission.  (See also path_resolution(7).)
82
83       EBADF  (symlinkat())  linkpath  is  relative  but  newdirfd  is neither
84              AT_FDCWD nor a valid file descriptor.
85
86       EDQUOT The user's quota of resources on the  filesystem  has  been  ex‐
87              hausted.   The resources could be inodes or disk blocks, depend‐
88              ing on the filesystem implementation.
89
90       EEXIST linkpath already exists.
91
92       EFAULT target or linkpath points outside your accessible address space.
93
94       EIO    An I/O error occurred.
95
96       ELOOP  Too many symbolic links were encountered in resolving linkpath.
97
98       ENAMETOOLONG
99              target or linkpath was too long.
100
101       ENOENT A directory component in linkpath does not exist or  is  a  dan‐
102              gling symbolic link, or target or linkpath is an empty string.
103
104       ENOENT (symlinkat())  linkpath  is  a  relative  pathname  and newdirfd
105              refers to a directory that has been deleted.
106
107       ENOMEM Insufficient kernel memory was available.
108
109       ENOSPC The device containing the file has no room for the new directory
110              entry.
111
112       ENOTDIR
113              A  component  used as a directory in linkpath is not, in fact, a
114              directory.
115
116       ENOTDIR
117              (symlinkat()) linkpath is relative and newdirfd is  a  file  de‐
118              scriptor referring to a file other than a directory.
119
120       EPERM  The filesystem containing linkpath does not support the creation
121              of symbolic links.
122
123       EROFS  linkpath is on a read-only filesystem.
124

STANDARDS

126       POSIX.1-2008.
127

HISTORY

129       symlink()
130              SVr4, 4.3BSD, POSIX.1-2001.
131
132       symlinkat()
133              POSIX.1-2008.  Linux 2.6.16, glibc 2.4.
134
135   glibc notes
136       On older kernels where symlinkat() is unavailable,  the  glibc  wrapper
137       function  falls back to the use of symlink().  When linkpath is a rela‐
138       tive pathname, glibc constructs a pathname based on the  symbolic  link
139       in /proc/self/fd that corresponds to the newdirfd argument.
140

NOTES

142       No checking of target is done.
143
144       Deleting  the  name referred to by a symbolic link will actually delete
145       the file (unless it also has other hard links).  If  this  behavior  is
146       not desired, use link(2).
147