1.\" $OpenBSD: link.2,v 1.18 2008/11/21 15:52:55 jasper Exp $ 2.\" $NetBSD: link.2,v 1.7 1995/02/27 12:34:01 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)link.2 8.3 (Berkeley) 1/12/94 32.\" 33.Dd $Mdocdate: November 21 2008 $ 34.Dt LINK 2 35.Os 36.Sh NAME 37.Nm link 38.Nd make hard link to a file 39.Sh SYNOPSIS 40.Fd #include <unistd.h> 41.Ft int 42.Fn link "const char *name1" "const char *name2" 43.Sh DESCRIPTION 44The 45.Fn link 46function atomically creates the specified directory entry (hard link) 47.Fa name2 48with the attributes of the underlying object pointed at by 49.Fa name1 . 50If the link is successful: the link count of the underlying object 51is incremented; 52.Fa name1 53and 54.Fa name2 55share equal access and rights to the underlying object. 56.Pp 57If 58.Fa name1 59is removed, the file 60.Fa name2 61is not deleted and the link count of the underlying object is decremented. 62.Pp 63.Fa name1 64must exist for the hard link to succeed and both 65.Fa name1 66and 67.Fa name2 68must be in the same file system. 69As mandated by POSIX.1 70.Fa name1 71may not be a directory. 72.Sh RETURN VALUES 73Upon successful completion, a value of 0 is returned. 74Otherwise, a value of \-1 is returned and 75.Va errno 76is set to indicate the error. 77.Sh ERRORS 78.Fn link 79will fail and no link will be created if: 80.Bl -tag -width Er 81.It Bq Er ENOTDIR 82A component of either path prefix is not a directory. 83.It Bq Er ENAMETOOLONG 84A component of a pathname exceeded 85.Dv {NAME_MAX} 86characters, or an entire path name exceeded 87.Dv {PATH_MAX} 88characters. 89.It Bq Er ENOENT 90A component of either path prefix does not exist. 91.It Bq Er EOPNOTSUPP 92The file system containing the file named by 93.Fa name1 94does not support links. 95.It Bq Er EMLINK 96The link count of the file named by 97.Fa name1 98would exceed 99.Dv LINK_MAX . 100.It Bq Er EACCES 101A component of either path prefix denies search permission. 102.It Bq Er EACCES 103The requested link requires writing in a directory with a mode 104that denies write permission. 105.It Bq Er ELOOP 106Too many symbolic links were encountered in translating one of the pathnames. 107.It Bq Er ENOENT 108The file named by 109.Fa name1 110does not exist. 111.It Bq Er EEXIST 112The link named by 113.Fa name2 114does exist. 115.It Bq Er EPERM 116The file named by 117.Fa name1 118is a directory and the effective 119user ID is not superuser, 120or the file system containing the file does not permit the use of 121.Fn link 122on a directory. 123.It Bq Er EPERM 124The file named by 125.Fa name1 126is flagged immutable or append-only. 127.It Bq Er EXDEV 128The link named by 129.Fa name2 130and the file named by 131.Fa name1 132are on different file systems. 133.It Bq Er ENOSPC 134The directory in which the entry for the new link is being placed 135cannot be extended because there is no space left on the file 136system containing the directory. 137.It Bq Er EDQUOT 138The directory in which the entry for the new link 139is being placed cannot be extended because the 140user's quota of disk blocks on the file system 141containing the directory has been exhausted. 142.It Bq Er EIO 143An I/O error occurred while reading from or writing to 144the file system to make the directory entry. 145.It Bq Er EROFS 146The requested link requires writing in a directory on a read-only file 147system. 148.It Bq Er EFAULT 149One of the pathnames specified 150is outside the process's allocated address space. 151.El 152.Sh SEE ALSO 153.Xr ln 1 , 154.Xr readlink 2 , 155.Xr symlink 2 , 156.Xr unlink 2 157.Sh STANDARDS 158The 159.Fn link 160function is expected to conform to 161.St -p1003.1-88 . 162