1.\" $NetBSD: link.2,v 1.13 1999/12/02 21:42:37 kleink 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 <unistd.h> 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. 105.It Bq Er EACCES 106The requested link requires writing in a directory with a mode 107that denies write permission. 108.It Bq Er ELOOP 109Too many symbolic links were encountered in translating one of the pathnames. 110.It Bq Er ENOENT 111The file named by 112.Fa name1 113does not exist. 114.It Bq Er EOPNOTSUPP 115The file system containing the file named by 116.Fa name1 117does not support links. 118.It Bq Er EMLINK 119The link count of the file named by 120.Fa name1 121would exceed 122.Dv {LINK_MAX}. 123.It Bq Er EEXIST 124The link named by 125.Fa name2 126does exist. 127.It Bq Er EPERM 128The file named by 129.Fa name1 130is a directory and the effective 131user ID is not super-user, 132or the file system containing the file does not permit the use of 133.Fn link 134on a directory. 135.It Bq Er EXDEV 136The link named by 137.Fa name2 138and the file named by 139.Fa name1 140are on different file systems. 141.It Bq Er ENOSPC 142The directory in which the entry for the new link is being placed 143cannot be extended because there is no space left on the file 144system containing the directory. 145.ne 3v 146.It Bq Er EDQUOT 147The directory in which the entry for the new link 148is being placed cannot be extended because the 149user's quota of disk blocks on the file system 150containing the directory has been exhausted. 151.It Bq Er EIO 152An I/O error occurred while reading from or writing to 153the file system to make the directory entry. 154.It Bq Er EROFS 155The requested link requires writing in a directory on a read-only file 156system. 157.It Bq Er EFAULT 158One of the pathnames specified 159is outside the process's allocated address space. 160.El 161.Sh SEE ALSO 162.Xr symlink 2 , 163.Xr unlink 2 164.Sh STANDARDS 165The 166.Fn link 167function conforms to 168.St -p1003.1-90 . 169