.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "SYMLINK" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" symlink 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
symlink \- make a symbolic link to a file
.SH SYNOPSIS
.LP
\fB#include <unistd.h>
.br
.sp
int symlink(const char *\fP\fIpath1\fP\fB, const char *\fP\fIpath2\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fIsymlink\fP() function shall create a symbolic link called \fIpath2\fP
that contains the string pointed to by
\fIpath1\fP ( \fIpath2\fP is the name of the symbolic link created,
\fIpath1\fP is the string contained in the symbolic
link).
.LP
The string pointed to by \fIpath1\fP shall be treated only as a character
string and shall not be validated as a pathname.
.LP
If the \fIsymlink\fP() function fails for any reason other than [EIO],
any file named by \fIpath2\fP shall be unaffected.
.SH RETURN VALUE
.LP
Upon successful completion, \fIsymlink\fP() shall return 0; otherwise,
it shall return -1 and set \fIerrno\fP to indicate the
error.
.SH ERRORS
.LP
The \fIsymlink\fP() function shall fail if:
.TP 7
.B EACCES
Write permission is denied in the directory where the symbolic link
is being created, or search permission is denied for a
component of the path prefix of \fIpath2\fP.
.TP 7
.B EEXIST
The \fIpath2\fP argument names an existing file or symbolic link.
.TP 7
.B EIO
An I/O error occurs while reading from or writing to the file system.
.TP 7
.B ELOOP
A loop exists in symbolic links encountered during resolution of the
\fIpath2\fP argument.
.TP 7
.B ENAMETOOLONG
The length of the \fIpath2\fP argument exceeds {PATH_MAX} or a pathname
component is longer than {NAME_MAX} or the length of the
\fIpath1\fP argument is longer than {SYMLINK_MAX}.
.TP 7
.B ENOENT
A component of \fIpath2\fP does not name an existing file or \fIpath2\fP
is an empty string.
.TP 7
.B ENOSPC
The directory in which the entry for the new symbolic link is being
placed cannot be extended because no space is left on the
file system containing the directory, or the new symbolic link cannot
be created because no space is left on the file system which
shall contain the link, or the file system is out of file-allocation
resources.
.TP 7
.B ENOTDIR
A component of the path prefix of \fIpath2\fP is not a directory.
.TP 7
.B EROFS
The new symbolic link would reside on a read-only file system.
.sp
.LP
The \fIsymlink\fP() function may fail if:
.TP 7
.B ELOOP
More than {SYMLOOP_MAX} symbolic links were encountered during resolution
of the \fIpath2\fP argument.
.TP 7
.B ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the \fIpath2\fP
argument, the length of the substituted pathname
string exceeded {PATH_MAX} bytes (including the terminating null byte),
or the length of the string pointed to by \fIpath1\fP
exceeded {SYMLINK_MAX}.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
Like a hard link, a symbolic link allows a file to have multiple logical
names. The presence of a hard link guarantees the
existence of a file, even after the original name has been removed.
A symbolic link provides no such assurance; in fact, the file
named by the \fIpath1\fP argument need not exist when the link is
created. A symbolic link can cross file system boundaries.
.LP
Normal permission checks are made on each component of the symbolic
link pathname during its resolution.
.SH RATIONALE
.LP
Since IEEE\ Std\ 1003.1-2001 does not require any association of file
times with symbolic links, there is no requirement
that file times be updated by \fIsymlink\fP().
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIlchown\fP(), \fIlink\fP(), \fIlstat\fP(), \fIopen\fP(), \fIreadlink\fP(),
\fIunlink\fP(),
the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<unistd.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .