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.El 147.Pp 148If 149.Fn linkat 150is passed the special value 151.Dv AT_FDCWD 152in the 153.Fa fd1 154or 155.Fa fd2 156parameter, the current working directory is used for the respective 157.Fa name 158argument. 159If both 160.Fa fd1 161and 162.Fa fd2 163have value 164.Dv AT_FDCWD , 165the behavior is identical to a call to 166.Fn link . 167Unless 168.Fa flag 169contains the 170.Dv AT_SYMLINK_FOLLOW, 171.Dv AT_SYMLINK_NOFOLLOW_ANY 172or the 173.Dv AT_RESOLVE_BENEATH 174flags. On OS X, not assigning AT_SYMLINK_FOLLOW, AT_SYMLINK_NOFOLLOW_ANY or AT_RESOLVE_BENEATH to 175.Fa flag 176may result in some file systems returning an error. 177.Sh RETURN VALUES 178Upon successful completion, a value of 0 is returned. Otherwise, 179a value of -1 is returned and 180.Va errno 181is set to indicate the error. 182.Sh ERRORS 183.Fn link 184will fail and no link will be created if: 185.Bl -tag -width Er 186.\" ========== 187.It Bq Er EACCES 188A component of either path prefix denies search permission. 189.\" ========== 190.It Bq Er EACCES 191The requested link requires writing in a directory with a mode 192that denies write permission. 193.\" ========== 194.It Bq Er EACCES 195The current process cannot access the existing file. 196.\" ========== 197.It Bq Er EDQUOT 198The directory in which the entry for the new link 199is being placed cannot be extended because the 200user's quota of disk blocks on the file system 201containing the directory has been exhausted. 202.\" ========== 203.It Bq Er EEXIST 204The link named by 205.Fa path2 206already exists. 207.\" ========== 208.It Bq Er EFAULT 209One of the pathnames specified 210is outside the process's allocated address space. 211.\" ========== 212.It Bq Er EIO 213An I/O error occurs while reading from or writing to 214the file system to make the directory entry. 215.\" ========== 216.It Bq Er ELOOP 217Too many symbolic links are encountered in translating one of the pathnames. 218This is taken to be indicative of a looping symbolic link. 219.\" ========== 220.It Bq Er EMLINK 221The file already has {LINK_MAX} links. 222.\" ========== 223.It Bq Er ENAMETOOLONG 224A component of a pathname exceeds 225.Dv {NAME_MAX} 226characters, or an entire path name exceeded 227.Dv {PATH_MAX} 228characters. 229.\" ========== 230.It Bq Er ENOENT 231A component of either path prefix does not exist, or is a dangling symbolic link. 232.\" ========== 233.It Bq Er ENOENT 234The file named by 235.Fa path1 236does not exist, or is a dangling symbolic link. 237.\" ========== 238.It Bq Er ENOSPC 239The directory in which the entry for the new link is being placed 240cannot be extended because there is no space left on the file 241system containing the directory. 242.\" ========== 243.It Bq Er ENOTDIR 244A component of either path prefix is not a directory. 245.\" ========== 246.It Bq Er EPERM 247The file named by 248.Fa path1 249is a directory. 250.\" ========== 251.It Bq Er EROFS 252The requested link requires writing in a directory 253on a read-only file system. 254.\" ========== 255.It Bq Er EXDEV 256The link named by 257.Fa path2 258and the file named by 259.Fa path1 260are on different file systems. 261.\" ========== 262.It Bq Er EDEADLK 263The file named by 264.Fa path1 265is a 266.Dq dataless 267file that must be materialized before being linked and the I/O policy of 268the current thread or process disallows file materialization 269.Po see 270.Xr getiopolicy_np 3 271.Pc . 272.El 273.Pp 274In addition to the errors returned by the 275.Fn link , 276the 277.Fn linkat 278system call may fail if: 279.Bl -tag -width Er 280.It Bq Er EBADF 281The 282.Fa name1 283or 284.Fa name2 285argument does not specify an absolute path and the 286.Fa fd1 287or 288.Fa fd2 289argument, respectively, is neither 290.Dv AT_FDCWD 291nor a valid file descriptor open for searching. 292.It Bq Er EINVAL 293The value of the 294.Fa flag 295argument is not valid. 296.It Bq Er ENOTSUP 297.Fa flag 298was not set to 299.Dv AT_SYMLINK_FOLLOW (some file systems only). 300.It Bq Er ENOTSUP 301The underlying file system does not support this call. 302.It Bq Er ENOTDIR 303The 304.Fa name1 305or 306.Fa name2 307argument is not an absolute path and 308.Fa fd1 309or 310.Fa fd2 , 311respectively, is neither 312.Dv AT_FDCWD 313nor a file descriptor associated with a directory. 314.It Bq Er ELOOP 315If AT_SYMLINK_NOFOLLOW_ANY was passed and a symbolic link was encountered in 316translating either the 317.Fa name1 318or 319.Fa name2 320arguments. 321.It Bq Er ENOTCAPABLE 322AT_RESOLVE_BENEATH was passed and 323.Fa path 324does not reside in the directory hierarchy beneath the starting directory encountered in 325translating either the 326.Fa name1 327or 328.Fa name2 329arguments. 330.El 331.Sh SEE ALSO 332.Xr symlink 2 , 333.Xr unlink 2 334.Sh STANDARDS 335The 336.Fn link 337function is expected to conform to 338.St -p1003.1-88 . 339The 340.Fn linkat 341system call is expected to conform to POSIX.1-2008 . 342