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

NAME

6       symlink - make a symbolic link to a file
7

SYNOPSIS

9       #include <unistd.h>
10
11       int symlink(const char *path1, const char *path2);
12
13

DESCRIPTION

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

RETURN VALUE

27       Upon successful completion, symlink() shall  return  0;  otherwise,  it
28       shall return -1 and set errno to indicate the error.
29

ERRORS

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

EXAMPLES

82       None.
83

APPLICATION USAGE

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

RATIONALE

96       Since IEEE Std 1003.1-2001 does not require  any  association  of  file
97       times  with  symbolic links, there is no requirement that file times be
98       updated by symlink().
99

FUTURE DIRECTIONS

101       None.
102

SEE ALSO

104       lchown() , link() , lstat() , open() , readlink() , unlink() , the Base
105       Definitions volume of IEEE Std 1003.1-2001, <unistd.h>
106

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