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