1.\" $NetBSD: link.2,v 1.26 2011/08/08 19:50:17 wiz Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993, 2011 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.Ft int 45.Fn linkat "int fd1" "const char *name1" "int fd2" "const char *name2" "int flags" 46.Sh DESCRIPTION 47The 48.Fn link 49function call 50atomically creates the specified directory entry (hard link) 51.Fa name2 52with the attributes of the underlying object pointed at by 53.Fa name1 . 54If the link is successful: the link count of the underlying object 55is incremented; 56.Fa name1 57and 58.Fa name2 59share equal access and rights 60to the 61underlying object. 62.Pp 63If 64.Fa name1 65is removed, the file 66.Fa name2 67is not deleted and the link count of the 68underlying object is 69decremented. 70.Pp 71.Fa name1 72must exist for the hard link to 73succeed and 74both 75.Fa name1 76and 77.Fa name2 78must be in the same file system. 79.Fa name1 80may not be a directory unless the caller is the super-user 81and the file system containing it supports linking to directories. 82.Pp 83When operating on a symlink, 84.Fn link 85resolves the symlink and creates a hard link on the target. 86.Fn linkat 87will do the same if 88.Dv AT_SYMLINK_FOLLOW 89is set in 90.Fa flags , 91but it will link on the symlink itself if the flag is clear. 92.Pp 93At the moment, 94.Fn linkat 95is partially implemented. 96It will return 97.Er ENOSYS 98for 99.Fa fd1 100and 101.Fa fd2 102values different than 103.Dv AT_FDCWD . 104.Sh RETURN VALUES 105Upon successful completion, a value of 0 is returned. 106Otherwise, a value of \-1 is returned and 107.Va errno 108is set to indicate the error. 109.Sh ERRORS 110.Fn link 111will fail and no link will be created if: 112.Bl -tag -width Er 113.It Bq Er EACCES 114A component of either path prefix denies search permission, or 115the requested link requires writing in a directory with a mode 116that denies write permission. 117.It Bq Er EDQUOT 118The directory in which the entry for the new link 119is being placed cannot be extended because the 120user's quota of disk blocks on the file system 121containing the directory has been exhausted. 122.It Bq Er EEXIST 123The link named by 124.Fa name2 125does exist. 126.It Bq Er EFAULT 127One of the pathnames specified 128is outside the process's allocated address space. 129.It Bq Er EIO 130An I/O error occurred while reading from or writing to 131the file system to make the directory entry. 132.It Bq Er ELOOP 133Too many symbolic links were encountered in translating one of the pathnames. 134.It Bq Er EMLINK 135The link count of the file named by 136.Fa name1 137would exceed 138.Dv {LINK_MAX} . 139.It Bq Er ENAMETOOLONG 140A component of a pathname exceeded 141.Brq Dv NAME_MAX 142characters, or an entire path name exceeded 143.Brq Dv PATH_MAX 144characters. 145.It Bq Er ENOENT 146A component of either path prefix does not exist, or the file named 147by 148.Fa name1 149does not exist. 150.It Bq Er ENOSPC 151The directory in which the entry for the new link is being placed 152cannot be extended because there is no space left on the file 153system containing the directory. 154.It Bq Er ENOTDIR 155A component of either path prefix is not a directory. 156.It Bq Er EOPNOTSUPP 157The file system containing the file named by 158.Fa name1 159does not support links. 160.It Bq Er EPERM 161The file named by 162.Fa name1 163is a directory and the effective 164user ID is not super-user, 165or the file system containing the file does not permit the use of 166.Fn link 167on a directory. 168.It Bq Er EROFS 169The requested link requires writing in a directory on a read-only file 170system. 171.It Bq Er EXDEV 172The link named by 173.Fa name2 174and the file named by 175.Fa name1 176are on different file systems. 177.El 178.Sh SEE ALSO 179.Xr symlink 2 , 180.Xr unlink 2 181.Sh STANDARDS 182The 183.Fn link 184function conforms to 185.St -p1003.1-90 . 186.Sh BUGS 187.Fn linkat 188is partially implemented. 189