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