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
11

NAME

13       symlink, symlinkat — make a symbolic link relative  to  directory  file
14       descriptor
15

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

71       Upon successful completion, these functions shall return 0.  Otherwise,
72       these functions shall return −1 and set errno to indicate the error.
73

ERRORS

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

EXAMPLES

136       None.
137

APPLICATION USAGE

139       Like  a hard link, a symbolic link allows a file to have multiple logi‐
140       cal names. The presence of a hard link guarantees the  existence  of  a
141       file,  even  after  the original name has been removed. A symbolic link
142       provides no such assurance; in fact, the file named by the path1  argu‐
143       ment need not exist when the link is created. A symbolic link can cross
144       file system boundaries.
145
146       Normal permission checks are made on each  component  of  the  symbolic
147       link pathname during its resolution.
148

RATIONALE

150       The  purpose of the symlinkat() function is to create symbolic links in
151       directories other than the current working directory  without  exposure
152       to  race conditions. Any part of the path of a file could be changed in
153       parallel to a call to symlink(), resulting in unspecified behavior.  By
154       opening  a  file descriptor for the target directory and using the sym‐
155       linkat() function it can be guaranteed that the created  symbolic  link
156       is located relative to the desired directory.
157

FUTURE DIRECTIONS

159       None.
160

SEE ALSO

162       fdopendir(), fstatat(), lchown(), link(), open(), readlink(), rename(),
163       unlink()
164
165       The Base Definitions volume of POSIX.1‐2008, <unistd.h>
166
168       Portions of this text are reprinted and reproduced in  electronic  form
169       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
170       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
171       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
172       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
173       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
174       event of any discrepancy between this version and the original IEEE and
175       The  Open Group Standard, the original IEEE and The Open Group Standard
176       is the referee document. The original Standard can be  obtained  online
177       at http://www.unix.org/online.html .
178
179       Any  typographical  or  formatting  errors that appear in this page are
180       most likely to have been introduced during the conversion of the source
181       files  to  man page format. To report such errors, see https://www.ker
182       nel.org/doc/man-pages/reporting_bugs.html .
183
184
185
186IEEE/The Open Group                  2013                          SYMLINK(3P)
Impressum