'\"macro stdmacro
.if n .pH g2.link @(#)link	40.17 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} link 2 "" "\&"
.if \nX=1 .ds x} link 2 ""
.if \nX=2 .ds x} link 2 "" "\&"
.if \nX=3 .ds x} link "" "" "\&"
.TH \*(x}
.SH NAME
\f4link\f1 \- link to a file
.SH SYNOPSIS
\f4#include <unistd.h>\f1
.PP
\f4int link(const char \(**path1, const char \(**path2);  \f1
.SH DESCRIPTION
.I path1\^
points to a
path name
naming an existing file.
.I path2\^
points to a
path name
naming the new directory entry to be created.
\f4link\fP
creates a new link (directory entry) for the existing file and
increments its link count by one.
.PP
Upon successful completion, \f4link\fP marks for update the \f4st_ctime\fP
field of the file. Also, the \f4st_ctime\fP and \f4st_mtime\fP fields of
the directory that contains the new entry are marked for update.
.PP
\f4link\fP
will fail and no link will be created if one or more of the following
are true:
.TP 20
\f4EACCES\fP
A component of either
path prefix
denies search permission.
.TP
\f4EACCES\fP
The requested link requires writing in a directory
with a mode
that denies write permission.
.TP
\f4EEXIST\fP
The link named by
.I path2\^
exists.
.TP
\f4EFAULT\fP
.I path\^
points outside the allocated address space of the process.
.TP
\f4EINTR\fP
A signal was caught during the \f4link\fP system call.
.TP
\f4ELOOP\fP
Too many symbolic links were encountered in translating \f2path\f1.
.TP
\f4EMLINK\fP
The maximum number of links to a file would be exceeded.
.TP
\f4EMULTIHOP\fP
Components of \f2path\f1 require hopping to multiple
remote machines
and file system type does not allow it.
.TP
\f4ENAMETOOLONG\fP
The length of the \f2path1\f1 or \f2path2\f1 argument exceeds {\f4PATH_MAX\f1}, or the
length of a \f2path1\f1 or \f2path2\f1 component exceeds {\f4NAME_MAX\f1} while
\f4_POSIX_NO_TRUNC\f1 is in effect.
.TP 20
\f4ENOTDIR\fP
A component of either
path prefix
is not a directory.
.TP
\f4ENOENT\fP
.I path1\^
or
.I path2\^
is a null path name.
.TP
\f4ENOENT\fP
A component of either
path prefix
does not exist.
.TP
\f4ENOENT\fP
The file named by
.I path1\^
does not exist.
.TP
\f4ENOLINK\fP
\f2path\f1 points to a remote machine and the link
to that machine is no longer active.
.TP
\f4ENOSPC\fP
the directory that would contain the link cannot be extended.
.TP
\f4EPERM\fP
The file named by
.I path1\^
is a directory and the effective user
.SM ID
is not super-user.
.TP
\f4EROFS\fP
The requested link requires writing in a directory on a read-only file system.
.TP
\f4EXDEV\fP
The link named by
.I path2\^
and the file named by
.I path1\^
are on different logical devices (file systems).
.SH "SEE ALSO"
\f4unlink\fP(2).
.SH "DIAGNOSTICS"
Upon successful completion, a value of 0 is returned.
Otherwise, a value of \-1 is returned and
\f4errno\fP
is set to indicate the error.
.\"	@(#)link.2	6.2 of 9/6/83
.Ee
