1SYMLINK(3P)                POSIX Programmer's Manual               SYMLINK(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       symlink, symlinkat — make a symbolic link
13

SYNOPSIS

15       #include <unistd.h>
16
17       int symlink(const char *path1, const char *path2);
18
19       #include <fcntl.h>
20
21       int symlinkat(const char *path1, int fd, const char *path2);
22

DESCRIPTION

24       The symlink() function shall create a symbolic link called  path2  that
25       contains  the string pointed to by path1 (path2 is the name of the sym‐
26       bolic link created, path1 is  the  string  contained  in  the  symbolic
27       link).
28
29       The  string  pointed  to by path1 shall be treated only as a string and
30       shall not be validated as a pathname.
31
32       If the symlink() function fails for any reason other  than  [EIO],  any
33       file named by path2 shall be unaffected.
34
35       If  path2  names a symbolic link, symlink() shall fail and set errno to
36       [EEXIST].
37
38       The symbolic link's user ID shall be set to the process' effective user
39       ID.  The  symbolic  link's group ID shall be set to the group ID of the
40       parent directory or to the effective group ID of the process. Implemen‐
41       tations  shall provide a way to initialize the symbolic link's group ID
42       to the group ID of the parent directory. Implementations may, but  need
43       not,  provide  an implementation-defined way to initialize the symbolic
44       link's group ID to the effective group ID of the calling process.
45
46       The values of the file mode bits for  the  created  symbolic  link  are
47       unspecified.  All  interfaces specified by POSIX.1‐2008 shall behave as
48       if the contents of symbolic links can always be read, except  that  the
49       value  of  the file mode bits returned in the st_mode field of the stat
50       structure is unspecified.
51
52       Upon successful completion, symlink() shall mark for  update  the  last
53       data  access, last data modification, and last file status change time‐
54       stamps of the symbolic link. Also, the last data modification and  last
55       file  status  change  timestamps of the directory that contains the new
56       entry shall be marked for update.
57
58       The symlinkat() function shall be equivalent to the symlink()  function
59       except  in the case where path2 specifies a relative path. In this case
60       the symbolic link is created relative to the directory associated  with
61       the file descriptor fd instead of the current working directory. If the
62       access mode of the open  file  description  associated  with  the  file
63       descriptor  is not O_SEARCH, the function shall check whether directory
64       searches are permitted using the current permissions of  the  directory
65       underlying  the  file  descriptor.  If the access mode is O_SEARCH, the
66       function shall not perform the check.
67
68       If symlinkat() is passed the special value AT_FDCWD in the  fd  parame‐
69       ter, the current working directory shall be used and the behavior shall
70       be identical to a call to symlink().
71

RETURN VALUE

73       Upon successful completion, these functions shall return 0.  Otherwise,
74       these functions shall return -1 and set errno to indicate the error.
75

ERRORS

77       These functions shall fail if:
78
79       EACCES Write  permission  is denied in the directory where the symbolic
80              link is being created, or search permission is denied for a com‐
81              ponent of the path prefix of path2.
82
83       EEXIST The path2 argument names an existing file.
84
85       EIO    An  I/O  error  occurs while reading from or writing to the file
86              system.
87
88       ELOOP  A loop exists in symbolic links encountered during resolution of
89              the path2 argument.
90
91       ENAMETOOLONG
92              The length of a component of the pathname specified by the path2
93              argument is longer than {NAME_MAX} or the length  of  the  path1
94              argument is longer than {SYMLINK_MAX}.
95
96       ENOENT A  component of the path prefix of path2 does not name an exist‐
97              ing file or path2 is an empty string.
98
99       ENOENT or ENOTDIR
100              The path2 argument contains at least one  non-<slash>  character
101              and  ends with one or more trailing <slash> characters. If path2
102              without the trailing <slash> characters would name  an  existing
103              file, an [ENOENT] error shall not occur.
104
105       ENOSPC The  directory  in  which the entry for the new symbolic link is
106              being placed cannot be extended because no space is left on  the
107              file  system  containing the directory, or the new symbolic link
108              cannot be created because no space is left on  the  file  system
109              which shall contain the link, or the file system is out of file-
110              allocation resources.
111
112       ENOTDIR
113              A component of the path prefix of path2 names an  existing  file
114              that is neither a directory nor a symbolic link to a directory.
115
116       EROFS  The new symbolic link would reside on a read-only file system.
117
118       The symlinkat() function shall fail if:
119
120       EACCES The  access mode of the open file description associated with fd
121              is not O_SEARCH and the permissions of the directory  underlying
122              fd do not permit directory searches.
123
124       EBADF  The  path2 argument does not specify an absolute path and the fd
125              argument is neither AT_FDCWD nor a valid  file  descriptor  open
126              for reading or searching.
127
128       ENOTDIR
129              The  path2  argument  is  not  an absolute path and fd is a file
130              descriptor associated with a non-directory file.
131
132       These functions may fail if:
133
134       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
135              resolution of the path2 argument.
136
137       ENAMETOOLONG
138              The  length of the path2 argument exceeds {PATH_MAX} or pathname
139              resolution of a symbolic link in the path2 argument produced  an
140              intermediate result with a length that exceeds {PATH_MAX}.
141
142       The following sections are informative.
143

EXAMPLES

145       None.
146

APPLICATION USAGE

148       Like  a hard link, a symbolic link allows a file to have multiple logi‐
149       cal names. The presence of a hard link guarantees the  existence  of  a
150       file,  even  after  the original name has been removed. A symbolic link
151       provides no such assurance; in fact, the file named by the path1  argu‐
152       ment need not exist when the link is created. A symbolic link can cross
153       file system boundaries.
154
155       Normal permission checks are made on each  component  of  the  symbolic
156       link pathname during its resolution.
157

RATIONALE

159       The  purpose of the symlinkat() function is to create symbolic links in
160       directories other than the current working directory  without  exposure
161       to  race conditions. Any part of the path of a file could be changed in
162       parallel to a call to symlink(), resulting in unspecified behavior.  By
163       opening  a  file descriptor for the target directory and using the sym‐
164       linkat() function it can be guaranteed that the created  symbolic  link
165       is located relative to the desired directory.
166

FUTURE DIRECTIONS

168       None.
169

SEE ALSO

171       fdopendir(), fstatat(), lchown(), link(), open(), readlink(), rename(),
172       unlink()
173
174       The Base Definitions volume of POSIX.1‐2017, <fcntl.h>, <unistd.h>
175
177       Portions of this text are reprinted and reproduced in  electronic  form
178       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
179       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
180       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
181       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
182       event of any discrepancy between this version and the original IEEE and
183       The Open Group Standard, the original IEEE and The Open Group  Standard
184       is  the  referee document. The original Standard can be obtained online
185       at http://www.opengroup.org/unix/online.html .
186
187       Any typographical or formatting errors that appear  in  this  page  are
188       most likely to have been introduced during the conversion of the source
189       files to man page format. To report such errors,  see  https://www.ker
190       nel.org/doc/man-pages/reporting_bugs.html .
191
192
193
194IEEE/The Open Group                  2017                          SYMLINK(3P)
Impressum