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