1.\" $OpenBSD: link.2,v 1.31 2024/07/18 15:38:57 millert 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: July 18 2024 $ 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 68For the hard link to succeed, 69.Fa name1 70must exist and not be a directory, and both 71.Fa name1 72and 73.Fa name2 74must be in the same file system. 75.Pp 76The 77.Fn linkat 78function is equivalent to 79.Fn link 80except that where 81.Fa name1 82or 83.Fa name2 84specifies a relative path, 85the directory entries linked are resolved relative to 86the directories associated with file descriptors 87.Fa fd1 88or 89.Fa fd2 90(respectively) instead of the current working directory. 91.Pp 92If 93.Fn linkat 94is passed the special value 95.Dv AT_FDCWD 96(defined in 97.In fcntl.h ) 98in the 99.Fa fd1 100or 101.Fa fd2 102parameter, the current working directory is used for resolving the respective 103.Fa name1 104or 105.Fa name2 106argument. 107.Pp 108The 109.Fa flag 110argument is the bitwise OR of zero or more of the following values: 111.Pp 112.Bl -tag -width AT_SYMLINK_FOLLOW -offset indent -compact 113.It Dv AT_SYMLINK_FOLLOW 114If 115.Fa name1 116names a symbolic link, 117a new link for the target of the symbolic link is created. 118.El 119.Pp 120If the 121.Dv AT_SYMLINK_FOLLOW 122flag is clear and 123.Fa name1 124names a symbolic link, a new link is created for the symbolic link 125.Fa name1 126and not its target. 127.Sh RETURN VALUES 128.Rv -std 129.Sh ERRORS 130.Fn link 131and 132.Fn linkat 133will fail and no link will be created if: 134.Bl -tag -width Er 135.It Bq Er ENOTDIR 136A component of either path prefix is not a directory. 137.It Bq Er ENAMETOOLONG 138A component of a pathname exceeded 139.Dv NAME_MAX 140characters, or an entire pathname (including the terminating NUL) 141exceeded 142.Dv PATH_MAX 143bytes. 144.It Bq Er ENOENT 145A component of either path prefix does not exist. 146.It Bq Er EOPNOTSUPP 147The file system containing the file named by 148.Fa name1 149does not support links. 150.It Bq Er EMLINK 151The link count of the file named by 152.Fa name1 153would exceed 154.Dv LINK_MAX . 155.It Bq Er EACCES 156A component of either path prefix denies search permission. 157.It Bq Er EACCES 158The requested link requires writing in a directory with a mode 159that denies write permission. 160.It Bq Er ELOOP 161Too many symbolic links were encountered in translating one of the pathnames. 162.It Bq Er ENOENT 163The file named by 164.Fa name1 165does not exist. 166.It Bq Er EEXIST 167The link named by 168.Fa name2 169does exist. 170.It Bq Er EPERM 171The file named by 172.Fa name1 173is a directory. 174.It Bq Er EPERM 175The file named by 176.Fa name1 177is flagged immutable or append-only. 178.It Bq Er EXDEV 179The link named by 180.Fa name2 181and the file named by 182.Fa name1 183are on different file systems. 184.It Bq Er ENOSPC 185The directory in which the entry for the new link is being placed 186cannot be extended because there is no space left on the file 187system containing the directory. 188.It Bq Er EDQUOT 189The directory in which the entry for the new link 190is being placed cannot be extended because the 191user's quota of disk blocks on the file system 192containing the directory has been exhausted. 193.It Bq Er EIO 194An I/O error occurred while reading from or writing to 195the file system to make the directory entry. 196.It Bq Er EROFS 197The requested link requires writing in a directory on a read-only file 198system. 199.It Bq Er EFAULT 200One of the pathnames specified 201is outside the process's allocated address space. 202.El 203.Pp 204Additionally, 205.Fn linkat 206will fail if: 207.Bl -tag -width Er 208.It Bq Er EINVAL 209The value of the 210.Fa flag 211argument was neither zero nor 212.Dv AT_SYMLINK_FOLLOW . 213.It Bq Er EBADF 214The 215.Fa name1 216or 217.Fa name2 218argument specifies a relative path and the 219.Fa fd1 220or 221.Fa fd2 222argument, respectively, is neither 223.Dv AT_FDCWD 224nor a valid file descriptor. 225.It Bq Er ENOTDIR 226The 227.Fa name1 228or 229.Fa name2 230argument specifies a relative path and the 231.Fa fd1 232or 233.Fa fd2 234argument, respectively, 235is a valid file descriptor but it does not reference a directory. 236.It Bq Er EACCES 237The 238.Fa name1 239or 240.Fa name2 241argument specifies a relative path but search permission is denied 242for the directory which the 243.Fa fd1 244or 245.Fa fd2 246file descriptor, respectively, references. 247.El 248.Sh SEE ALSO 249.Xr ln 1 , 250.Xr readlink 2 , 251.Xr symlink 2 , 252.Xr unlink 2 253.Sh STANDARDS 254The 255.Fn link 256and 257.Fn linkat 258functions are expected to conform to 259.St -p1003.1-2008 . 260.Sh HISTORY 261The 262.Fn link 263system call first appeared in 264.At v1 . 265The 266.Fn linkat 267function appeared in 268.Ox 5.0 . 269