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 - make a symbolic link to a file
13

SYNOPSIS

15       #include <unistd.h>
16
17       int symlink(const char *path1, const char *path2);
18
19

DESCRIPTION

21       The symlink() function shall create a symbolic link called  path2  that
22       contains the string pointed to by path1 ( path2 is the name of the sym‐
23       bolic link created, path1 is  the  string  contained  in  the  symbolic
24       link).
25
26       The  string  pointed  to  by path1 shall be treated only as a character
27       string and shall not be validated as a pathname.
28
29       If the symlink() function fails for any reason other  than  [EIO],  any
30       file named by path2 shall be unaffected.
31

RETURN VALUE

33       Upon  successful  completion,  symlink()  shall return 0; otherwise, it
34       shall return -1 and set errno to indicate the error.
35

ERRORS

37       The symlink() function shall fail if:
38
39       EACCES Write permission is denied in the directory where  the  symbolic
40              link is being created, or search permission is denied for a com‐
41              ponent of the path prefix of path2.
42
43       EEXIST The path2 argument names an existing file or symbolic link.
44
45       EIO    An I/O error occurs while reading from or writing  to  the  file
46              system.
47
48       ELOOP  A loop exists in symbolic links encountered during resolution of
49              the path2 argument.
50
51       ENAMETOOLONG
52              The length of the path2 argument exceeds {PATH_MAX} or  a  path‐
53              name  component  is  longer than {NAME_MAX} or the length of the
54              path1 argument is longer than {SYMLINK_MAX}.
55
56       ENOENT A component of path2 does not name an existing file or path2  is
57              an empty string.
58
59       ENOSPC The  directory  in  which the entry for the new symbolic link is
60              being placed cannot be extended because no space is left on  the
61              file  system  containing the directory, or the new symbolic link
62              cannot be created because no space is left on  the  file  system
63              which shall contain the link, or the file system is out of file-
64              allocation resources.
65
66       ENOTDIR
67              A component of the path prefix of path2 is not a directory.
68
69       EROFS  The new symbolic link would reside on a read-only file system.
70
71
72       The symlink() function may fail if:
73
74       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
75              resolution of the path2 argument.
76
77       ENAMETOOLONG
78              As a result of encountering a symbolic link in resolution of the
79              path2 argument, the length of the  substituted  pathname  string
80              exceeded {PATH_MAX} bytes (including the terminating null byte),
81              or the length of the string pointed to by path1  exceeded  {SYM‐
82              LINK_MAX}.
83
84
85       The following sections are informative.
86

EXAMPLES

88       None.
89

APPLICATION USAGE

91       Like  a hard link, a symbolic link allows a file to have multiple logi‐
92       cal names. The presence of a hard link guarantees the  existence  of  a
93       file,  even  after the original name has been removed.  A symbolic link
94       provides no such assurance; in fact, the file named by the path1  argu‐
95       ment need not exist when the link is created. A symbolic link can cross
96       file system boundaries.
97
98       Normal permission checks are made on each  component  of  the  symbolic
99       link pathname during its resolution.
100

RATIONALE

102       Since  IEEE Std 1003.1-2001  does  not  require any association of file
103       times with symbolic links, there is no requirement that file  times  be
104       updated by symlink().
105

FUTURE DIRECTIONS

107       None.
108

SEE ALSO

110       lchown(), link(), lstat(), open(), readlink(), unlink(), the Base Defi‐
111       nitions volume of IEEE Std 1003.1-2001, <unistd.h>
112

114       Portions of this text are reprinted and reproduced in  electronic  form
115       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
116       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
117       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
118       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
119       event of any discrepancy between this version and the original IEEE and
120       The Open Group Standard, the original IEEE and The Open Group  Standard
121       is  the  referee document. The original Standard can be obtained online
122       at http://www.opengroup.org/unix/online.html .
123
124
125
126IEEE/The Open Group                  2003                          SYMLINK(3P)
Impressum