1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)link.2 8.3 (Berkeley) 1/12/94 29.\" $FreeBSD: src/lib/libc/sys/link.2,v 1.11.2.7 2001/12/14 18:34:01 ru Exp $ 30.\" 31.Dd July 31, 2012 32.Dt LINK 2 33.Os 34.Sh NAME 35.Nm link , 36.Nm linkat 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. 81.Pp 82When operating on a symlink, 83.Fn link 84resolves the symlink and creates a hard link on the target. 85.Fn linkat 86will do the same if 87.Dv AT_SYMLINK_FOLLOW 88is set in 89.Fa flags , 90but it will link on the symlink itself if the flag is clear. 91.Pp 92The 93.Fn linkat 94system call is equivalent to 95.Fn link 96except in the case where either 97.Fa name1 98or 99.Fa name2 100or both are relative paths. 101In this case a relative path 102.Fa name1 103is interpreted relative to the directory associated with the file descriptor 104.Fa fd1 105instead of the current working directory and similarly for 106.Fa name2 107and the file descriptor 108.Fa fd2 . 109If 110.Fa fd1 111or 112.Fa fd2 113has the special value 114.Dv AT_FDCWD 115then 116.Fa name1 117or 118.Fa name2 119respectively is interpreted relative to the current working directory. 120.Sh RETURN VALUES 121.Rv -std link 122.Sh ERRORS 123.Fn Link 124will fail and no link will be created if: 125.Bl -tag -width Er 126.It Bq Er ENOTDIR 127A component of either path prefix is not a directory. 128.It Bq Er ENAMETOOLONG 129A component of either pathname exceeded 255 characters, 130or entire length of either path name exceeded 1023 characters. 131.It Bq Er ENOENT 132A component of either path prefix does not exist. 133.It Bq Er EOPNOTSUPP 134The file system containing the file named by 135.Fa name1 136does not support links. 137.It Bq Er EMLINK 138The link count of the file named by 139.Fa name1 140would exceed 32767. 141.It Bq Er EACCES 142A component of either path prefix denies search permission. 143.It Bq Er EACCES 144The requested link requires writing in a directory with a mode 145that denies write permission. 146.It Bq Er ELOOP 147Too many symbolic links were encountered in translating one of the pathnames. 148.It Bq Er ENOENT 149The file named by 150.Fa name1 151does not exist. 152.It Bq Er EEXIST 153The link named by 154.Fa name2 155does exist. 156.It Bq Er EPERM 157The named file has its immutable or append-only flag set (see 158.Xr chflags 2 ) . 159.It Bq Er EPERM 160The file named by 161.Fa name1 162is a directory. 163.It Bq Er EXDEV 164The link named by 165.Fa name2 166and the file named by 167.Fa name1 168are on different file systems. 169.It Bq Er ENOSPC 170The directory in which the entry for the new link is being placed 171cannot be extended because there is no space left on the file 172system containing the directory. 173.It Bq Er EDQUOT 174The directory in which the entry for the new link 175is being placed cannot be extended because the 176user's quota of disk blocks on the file system 177containing the directory has been exhausted. 178.It Bq Er EIO 179An I/O error occurred while reading from or writing to 180the file system to make the directory entry. 181.It Bq Er EROFS 182The requested link requires writing in a directory on a read-only file 183system. 184.It Bq Er EFAULT 185One of the pathnames specified 186is outside the process's allocated address space. 187.El 188.Pp 189In addition to the errors returned by the 190.Fn link 191syscall, the 192.Fn linkat 193system call may fail if: 194.Bl -tag -width Er 195.It Bq Er EBADF 196The 197.Fa name1 198or 199.Fa name2 200argument does not specify an absolute path and the 201.Fa fd1 202or 203.Fa fd2 204argument, respectively, is neither 205.Dv AT_FDCWD 206nor a valid file descriptor open for searching. 207.It Bq Er ENOTDIR 208The 209.Fa name1 210or 211.Fa name2 212argument is not an absolute path and 213.Fa fd1 214or 215.Fa fd2 , 216respectively, is neither 217.Dv AT_FDCWD 218nor a file descriptor associated with a directory. 219.El 220.Sh SEE ALSO 221.Xr readlink 2 , 222.Xr symlink 2 , 223.Xr unlink 2 224.Sh STANDARDS 225The 226.Fn link 227function call is expected to conform to 228.St -p1003.1-90 . 229.Sh HISTORY 230A 231.Fn link 232function call appeared in 233.At v7 . 234The 235.Fn linkat 236system call appeared in 237.Dx 3.1 . 238.Pp 239The 240.Fn link 241system call traditionally allows the super-user to link directories which 242corrupts the filesystem coherency. This implementation no longer permits 243it. 244