1.\" $OpenBSD: link.2,v 1.29 2015/09/10 17:55:21 schwarze Exp $ 2.\" $NetBSD: link.2,v 1.7 1995/02/27 12:34:01 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)link.2 8.3 (Berkeley) 1/12/94 32.\" 33.Dd $Mdocdate: September 10 2015 $ 34.Dt LINK 2 35.Os 36.Sh NAME 37.Nm link , 38.Nm linkat 39.Nd make hard link to a file 40.Sh SYNOPSIS 41.In unistd.h 42.Ft int 43.Fn link "const char *name1" "const char *name2" 44.In fcntl.h 45.In unistd.h 46.Ft int 47.Fn linkat "int fd1" "const char *name1" "int fd2" "const char *name2" "int flag" 48.Sh DESCRIPTION 49The 50.Fn link 51function atomically creates the specified directory entry (hard link) 52.Fa name2 53with the attributes of the underlying object pointed at by 54.Fa name1 . 55If the link is successful: the link count of the underlying object 56is incremented; 57.Fa name1 58and 59.Fa name2 60share equal access and rights to the underlying object. 61.Pp 62If 63.Fa name1 64is removed, the file 65.Fa name2 66is not deleted and the link count of the underlying object is decremented. 67.Pp 68.Fa name1 69must exist for the hard link to succeed and both 70.Fa name1 71and 72.Fa name2 73must be in the same file system. 74As mandated by POSIX.1 75.Fa name1 76may not be a directory. 77.Pp 78The 79.Fn linkat 80function is equivalent to 81.Fn link 82except that where 83.Fa name1 84or 85.Fa name2 86specifies a relative path, 87the directory entries linked are resolved relative to 88the directories associated with file descriptors 89.Fa fd1 90or 91.Fa fd2 92(respectively) instead of the current working directory. 93.Pp 94If 95.Fn linkat 96is passed the special value 97.Dv AT_FDCWD 98(defined in 99.In fcntl.h ) 100in the 101.Fa fd1 102or 103.Fa fd2 104parameter, the current working directory is used for resolving the respective 105.Fa name1 106or 107.Fa name2 108argument. 109.Pp 110The 111.Fa flag 112argument is the bitwise OR of zero or more of the following values: 113.Pp 114.Bl -tag -width AT_SYMLINK_FOLLOW -offset indent -compact 115.It Dv AT_SYMLINK_FOLLOW 116If 117.Fa name1 118names a symbolic link, 119a new link for the target of the symbolic link is created. 120.El 121.Pp 122If the 123.Dv AT_SYMLINK_FOLLOW 124flag is clear and 125.Fa name1 126names a symbolic link, a new link is created for the symbolic link 127.Fa name1 128and not its target. 129.Sh RETURN VALUES 130.Rv -std 131.Sh ERRORS 132.Fn link 133and 134.Fn linkat 135will fail and no link will be created if: 136.Bl -tag -width Er 137.It Bq Er ENOTDIR 138A component of either path prefix is not a directory. 139.It Bq Er ENAMETOOLONG 140A component of a pathname exceeded 141.Dv NAME_MAX 142characters, or an entire pathname (including the terminating NUL) 143exceeded 144.Dv PATH_MAX 145bytes. 146.It Bq Er ENOENT 147A component of either path prefix does not exist. 148.It Bq Er EOPNOTSUPP 149The file system containing the file named by 150.Fa name1 151does not support links. 152.It Bq Er EMLINK 153The link count of the file named by 154.Fa name1 155would exceed 156.Dv LINK_MAX . 157.It Bq Er EACCES 158A component of either path prefix denies search permission. 159.It Bq Er EACCES 160The requested link requires writing in a directory with a mode 161that denies write permission. 162.It Bq Er ELOOP 163Too many symbolic links were encountered in translating one of the pathnames. 164.It Bq Er ENOENT 165The file named by 166.Fa name1 167does not exist. 168.It Bq Er EEXIST 169The link named by 170.Fa name2 171does exist. 172.It Bq Er EPERM 173The file named by 174.Fa name1 175is a directory and the effective 176user ID is not superuser, 177or the file system containing the file does not permit the use of 178.Fn link 179on a directory. 180.It Bq Er EPERM 181The file named by 182.Fa name1 183is flagged immutable or append-only. 184.It Bq Er EXDEV 185The link named by 186.Fa name2 187and the file named by 188.Fa name1 189are on different file systems. 190.It Bq Er ENOSPC 191The directory in which the entry for the new link is being placed 192cannot be extended because there is no space left on the file 193system containing the directory. 194.It Bq Er EDQUOT 195The directory in which the entry for the new link 196is being placed cannot be extended because the 197user's quota of disk blocks on the file system 198containing the directory has been exhausted. 199.It Bq Er EIO 200An I/O error occurred while reading from or writing to 201the file system to make the directory entry. 202.It Bq Er EROFS 203The requested link requires writing in a directory on a read-only file 204system. 205.It Bq Er EFAULT 206One of the pathnames specified 207is outside the process's allocated address space. 208.El 209.Pp 210Additionally, 211.Fn linkat 212will fail if: 213.Bl -tag -width Er 214.It Bq Er EINVAL 215The value of the 216.Fa flag 217argument was neither zero nor 218.Dv AT_SYMLINK_FOLLOW . 219.It Bq Er EBADF 220The 221.Fa name1 222or 223.Fa name2 224argument specifies a relative path and the 225.Fa fd1 226or 227.Fa fd2 228argument, respectively, is neither 229.Dv AT_FDCWD 230nor a valid file descriptor. 231.It Bq Er ENOTDIR 232The 233.Fa name1 234or 235.Fa name2 236argument specifies a relative path and the 237.Fa fd1 238or 239.Fa fd2 240argument, respectively, 241is a valid file descriptor but it does not reference a directory. 242.It Bq Er EACCES 243The 244.Fa name1 245or 246.Fa name2 247argument specifies a relative path but search permission is denied 248for the directory which the 249.Fa fd1 250or 251.Fa fd2 252file descriptor, respectively, references. 253.El 254.Sh SEE ALSO 255.Xr ln 1 , 256.Xr readlink 2 , 257.Xr symlink 2 , 258.Xr unlink 2 259.Sh STANDARDS 260The 261.Fn link 262and 263.Fn linkat 264functions are expected to conform to 265.St -p1003.1-2008 . 266.Sh HISTORY 267The 268.Fn link 269system call first appeared in 270.At v1 . 271The 272.Fn linkat 273function appeared in 274.Ox 5.0 . 275