1.\" $NetBSD: link.2,v 1.7 1995/02/27 12:34:01 cgd Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)link.2 8.3 (Berkeley) 1/12/94 35.\" 36.Dd June 3, 2021 37.Dt LINK 2 38.Os BSD 4 39.Sh NAME 40.Nm link , 41.Nm linkat 42.Nd make a hard file link 43.Sh SYNOPSIS 44.Fd #include <unistd.h> 45.Ft int 46.Fo link 47.Fa "const char *path1" 48.Fa "const char *path2" 49.Fc 50.Ft int 51.Fo linkat 52.Fa "int fd1" "const char *name1" "int fd2" "const char *name2" "int flag" 53.Fc 54.Sh DESCRIPTION 55The 56.Fn link 57function call 58atomically creates the specified directory entry (hard link) 59.Fa path2 60with the attributes of the underlying object pointed at by 61.Fa path1 . 62If the link is successful, 63the link count of the underlying object is incremented; 64.Fa path1 65and 66.Fa path2 67share equal access and rights 68to the 69underlying object. 70.Pp 71If 72.Fa path1 73is removed, the file 74.Fa path2 75is not deleted and the link count of the 76underlying object is 77decremented. 78.Pp 79In order for the system call to succeed, 80.Fa path1 81must exist and both 82.Fa path1 83and 84.Fa path2 85must be in the same file system. 86As mandated by POSIX.1, 87.Fa path1 88may not be a directory. 89.Pp 90.Fn link 91will resolve and follow symbolic links contained within both 92.Fa path1 93and 94.Fa path2 . 95If the last component of 96.Fa path1 97is a symbolic link, 98.Fn link 99will point the hard link, 100.Fa path2 , 101to the underlying object pointed to by 102.Fa path1 , 103not to the symbolic link itself. 104.Pp 105The 106.Fn linkat 107system call is equivalent to 108.Fa link 109except in the case where either 110.Fa name1 111or 112.Fa name2 113or both are relative paths. 114In this case a relative path 115.Fa name1 116is interpreted relative to 117the directory associated with the file descriptor 118.Fa fd1 119instead of the current working directory and similarly for 120.Fa name2 121and the file descriptor 122.Fa fd2 . 123.Pp 124Values for 125.Fa flag 126are constructed by a bitwise-inclusive OR of flags from the following 127list, defined in 128.In fcntl.h : 129.Bl -tag -width AT_SYMLINK_NOFOLLOW_ANY 130.It Dv AT_SYMLINK_FOLLOW 131If 132.Fa name1 133names a symbolic link, a new link for the target of the symbolic link is 134created. 135.It Dv AT_SYMLINK_NOFOLLOW_ANY 136If 137.Fa name1 138names a symbolic link, a new link for the symbolic link is 139created. 140If a symbolic link is encountered during pathname resolution, an error is returned. 141.It Dv AT_RESOLVE_BENEATH 142If 143.Fa name1 144does not reside in the hierarchy beneath the starting directory, 145an error is returned. 146.It Dv AT_UNIQUE 147If 148.Fa name1 149resolves to a vnode with multiple hard links, 150an error is returned. 151.El 152.Pp 153If 154.Fn linkat 155is passed the special value 156.Dv AT_FDCWD 157in the 158.Fa fd1 159or 160.Fa fd2 161parameter, the current working directory is used for the respective 162.Fa name 163argument. 164If both 165.Fa fd1 166and 167.Fa fd2 168have value 169.Dv AT_FDCWD , 170the behavior is identical to a call to 171.Fn link . 172Unless 173.Fa flag 174contains the 175.Dv AT_SYMLINK_FOLLOW, 176.Dv AT_SYMLINK_NOFOLLOW_ANY, 177.Dv AT_RESOLVE_BENEATH 178or the 179.Dv AT_UNIQUE 180flags. On OS X, not assigning AT_SYMLINK_FOLLOW, AT_SYMLINK_NOFOLLOW_ANY, AT_RESOLVE_BENEATH or AT_UNIQUE to 181.Fa flag 182may result in some file systems returning an error. 183.Sh RETURN VALUES 184Upon successful completion, a value of 0 is returned. Otherwise, 185a value of -1 is returned and 186.Va errno 187is set to indicate the error. 188.Sh ERRORS 189.Fn link 190will fail and no link will be created if: 191.Bl -tag -width Er 192.\" ========== 193.It Bq Er EACCES 194A component of either path prefix denies search permission. 195.\" ========== 196.It Bq Er EACCES 197The requested link requires writing in a directory with a mode 198that denies write permission. 199.\" ========== 200.It Bq Er EACCES 201The current process cannot access the existing file. 202.\" ========== 203.It Bq Er EDQUOT 204The directory in which the entry for the new link 205is being placed cannot be extended because the 206user's quota of disk blocks on the file system 207containing the directory has been exhausted. 208.\" ========== 209.It Bq Er EEXIST 210The link named by 211.Fa path2 212already exists. 213.\" ========== 214.It Bq Er EFAULT 215One of the pathnames specified 216is outside the process's allocated address space. 217.\" ========== 218.It Bq Er EIO 219An I/O error occurs while reading from or writing to 220the file system to make the directory entry. 221.\" ========== 222.It Bq Er ELOOP 223Too many symbolic links are encountered in translating one of the pathnames. 224This is taken to be indicative of a looping symbolic link. 225.\" ========== 226.It Bq Er EMLINK 227The file already has {LINK_MAX} links. 228.\" ========== 229.It Bq Er ENAMETOOLONG 230A component of a pathname exceeds 231.Dv {NAME_MAX} 232characters, or an entire path name exceeded 233.Dv {PATH_MAX} 234characters. 235.\" ========== 236.It Bq Er ENOENT 237A component of either path prefix does not exist, or is a dangling symbolic link. 238.\" ========== 239.It Bq Er ENOENT 240The file named by 241.Fa path1 242does not exist, or is a dangling symbolic link. 243.\" ========== 244.It Bq Er ENOSPC 245The directory in which the entry for the new link is being placed 246cannot be extended because there is no space left on the file 247system containing the directory. 248.\" ========== 249.It Bq Er ENOTDIR 250A component of either path prefix is not a directory. 251.\" ========== 252.It Bq Er EPERM 253The file named by 254.Fa path1 255is a directory. 256.\" ========== 257.It Bq Er EROFS 258The requested link requires writing in a directory 259on a read-only file system. 260.\" ========== 261.It Bq Er EXDEV 262The link named by 263.Fa path2 264and the file named by 265.Fa path1 266are on different file systems. 267.\" ========== 268.It Bq Er EDEADLK 269The file named by 270.Fa path1 271is a 272.Dq dataless 273file that must be materialized before being linked and the I/O policy of 274the current thread or process disallows file materialization 275.Po see 276.Xr getiopolicy_np 3 277.Pc . 278.El 279.Pp 280In addition to the errors returned by the 281.Fn link , 282the 283.Fn linkat 284system call may fail if: 285.Bl -tag -width Er 286.It Bq Er EBADF 287The 288.Fa name1 289or 290.Fa name2 291argument does not specify an absolute path and the 292.Fa fd1 293or 294.Fa fd2 295argument, respectively, is neither 296.Dv AT_FDCWD 297nor a valid file descriptor open for searching. 298.It Bq Er EINVAL 299The value of the 300.Fa flag 301argument is not valid. 302.It Bq Er ENOTSUP 303.Fa flag 304was not set to 305.Dv AT_SYMLINK_FOLLOW (some file systems only). 306.It Bq Er ENOTSUP 307The underlying file system does not support this call. 308.It Bq Er ENOTDIR 309The 310.Fa name1 311or 312.Fa name2 313argument is not an absolute path and 314.Fa fd1 315or 316.Fa fd2 , 317respectively, is neither 318.Dv AT_FDCWD 319nor a file descriptor associated with a directory. 320.It Bq Er ELOOP 321If AT_SYMLINK_NOFOLLOW_ANY was passed and a symbolic link was encountered in 322translating either the 323.Fa name1 324or 325.Fa name2 326arguments. 327.It Bq Er ENOTCAPABLE 328AT_RESOLVE_BENEATH was passed and 329.Fa path 330does not reside in the directory hierarchy beneath the starting directory encountered in 331translating either the 332.Fa name1 333or 334.Fa name2 335arguments. 336.It Bq Er ENOTCAPABLE 337The flag parameter has the 338.Dv AT_UNIQUE 339bit set and 340.Fa name1 341resolves to a vnode with multiple links. 342.El 343.Sh SEE ALSO 344.Xr symlink 2 , 345.Xr unlink 2 346.Sh STANDARDS 347The 348.Fn link 349function is expected to conform to 350.St -p1003.1-88 . 351The 352.Fn linkat 353system call is expected to conform to POSIX.1-2008 . 354