X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/9bccf70c0258c7cac2dcb80011b2a964d884c552..bb59bff194111743b33cc36712410b5656329d3c:/bsd/man/man2/link.2 diff --git a/bsd/man/man2/link.2 b/bsd/man/man2/link.2 index 2a6f8b66c..35010cab7 100644 --- a/bsd/man/man2/link.2 +++ b/bsd/man/man2/link.2 @@ -33,52 +33,137 @@ .\" .\" @(#)link.2 8.3 (Berkeley) 1/12/94 .\" -.Dd January 12, 1994 +.Dd October 29, 2008 .Dt LINK 2 .Os BSD 4 .Sh NAME -.Nm link +.Nm link , +.Nm linkat .Nd make a hard file link .Sh SYNOPSIS .Fd #include .Ft int -.Fn link "const char *name1" "const char *name2" +.Fo link +.Fa "const char *path1" +.Fa "const char *path2" +.Fc +.Ft int +.Fo linkat +.Fa "int fd1" "const char *name1" "int fd2" "const char *name2" "int flag" +.Fc .Sh DESCRIPTION The .Fn link function call atomically creates the specified directory entry (hard link) -.Fa name2 +.Fa path2 with the attributes of the underlying object pointed at by -.Fa name1 -If the link is successful: the link count of the underlying object -is incremented; -.Fa name1 +.Fa path1 . +If the link is successful, +the link count of the underlying object is incremented; +.Fa path1 and -.Fa name2 +.Fa path2 share equal access and rights to the underlying object. .Pp If -.Fa name1 +.Fa path1 is removed, the file -.Fa name2 +.Fa path2 is not deleted and the link count of the underlying object is decremented. .Pp -.Fa Name1 -must exist for the hard link to -succeed and -both -.Fa name1 +In order for the system call to succeed, +.Fa path1 +must exist and both +.Fa path1 and -.Fa name2 +.Fa path2 must be in the same file system. -As mandated by POSIX.1 -.Fa name1 +As mandated by POSIX.1, +.Fa path1 may not be a directory. +.Pp +.Fn link +will resolve and follow symbolic links contained within both +.Fa path1 +and +.Fa path2 . +If the last component of +.Fa path1 +is a symbolic link, +.Fn link +will point the hard link, +.Fa path2 , +to the underlying object pointed to by +.Fa path1 , +not to the symbolic link itself. +.Pp +The +.Fn linkat +system call is equivalent to +.Fa link +except in the case where either +.Fa name1 +or +.Fa name2 +or both are relative paths. +In this case a relative path +.Fa name1 +is interpreted relative to +the directory associated with the file descriptor +.Fa fd1 +instead of the current working directory and similarly for +.Fa name2 +and the file descriptor +.Fa fd2 . +.Pp +Values for +.Fa flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.In fcntl.h : +.Bl -tag -width indent +.It Dv AT_SYMLINK_FOLLOW +If +.Fa name1 +names a symbolic link, a new link for the target of the symbolic link is +created. +.El +.Pp +If +.Fn linkat +is passed the special value +.Dv AT_FDCWD +in the +.Fa fd1 +or +.Fa fd2 +parameter, the current working directory is used for the respective +.Fa name +argument. +If both +.Fa fd1 +and +.Fa fd2 +have value +.Dv AT_FDCWD , +the behavior is identical to a call to +.Fn link . +Unless +.Fa flag +contains the +.Dv AT_SYMLINK_FOLLOW +flag, if +.Fa name1 +names a symbolic link, a new link is created for the symbolic link +.Fa name1 +and not its target. On OS X, not assigning AT_SYMLINK_FOLLOW to +.Fa flag +may result in some filesystems returning an error. .Sh RETURN VALUES Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and @@ -88,60 +173,121 @@ is set to indicate the error. .Fn Link will fail and no link will be created if: .Bl -tag -width Er -.It Bq Er ENOTDIR -A component of either path prefix is not a directory. -.It Bq Er ENAMETOOLONG -A component of a pathname exceeded -.Dv {NAME_MAX} -characters, or an entire path name exceeded -.Dv {PATH_MAX} -characters. -.It Bq Er ENOENT -A component of either path prefix does not exist. +.\" ========== .It Bq Er EACCES A component of either path prefix denies search permission. +.\" ========== .It Bq Er EACCES The requested link requires writing in a directory with a mode that denies write permission. +.\" ========== +.It Bq Er EACCES +The current process cannot access the existing file. +.\" ========== +.It Bq Er EDQUOT +The directory in which the entry for the new link +is being placed cannot be extended because the +user's quota of disk blocks on the file system +containing the directory has been exhausted. +.\" ========== +.It Bq Er EEXIST +The link named by +.Fa path2 +already exists. +.\" ========== +.It Bq Er EFAULT +One of the pathnames specified +is outside the process's allocated address space. +.\" ========== +.It Bq Er EIO +An I/O error occurs while reading from or writing to +the file system to make the directory entry. +.\" ========== .It Bq Er ELOOP -Too many symbolic links were encountered in translating one of the pathnames. +Too many symbolic links are encountered in translating one of the pathnames. +This is taken to be indicative of a looping symbolic link. +.\" ========== +.It Bq Er EMLINK +The file already has {LINK_MAX} links. +.\" ========== +.It Bq Er ENAMETOOLONG +A component of a pathname exceeds +.Dv {NAME_MAX} +characters, or an entire path name exceeded +.Dv {PATH_MAX} +characters. +.\" ========== +.It Bq Er ENOENT +A component of either path prefix does not exist, or is a dangling symbolic link. +.\" ========== .It Bq Er ENOENT The file named by -.Fa name1 -does not exist. -.It Bq Er EEXIST -The link named by -.Fa name2 -does exist. +.Fa path1 +does not exist, or is a dangling symbolic link. +.\" ========== +.It Bq Er ENOSPC +The directory in which the entry for the new link is being placed +cannot be extended because there is no space left on the file +system containing the directory. +.\" ========== +.It Bq Er ENOTDIR +A component of either path prefix is not a directory. +.\" ========== .It Bq Er EPERM The file named by -.Fa name1 +.Fa path1 is a directory. +.\" ========== +.It Bq Er EROFS +The requested link requires writing in a directory +on a read-only file system. +.\" ========== .It Bq Er EXDEV The link named by -.Fa name2 +.Fa path2 and the file named by -.Fa name1 +.Fa path1 are on different file systems. -.It Bq Er ENOSPC -The directory in which the entry for the new link is being placed -cannot be extended because there is no space left on the file -system containing the directory. -.ne 3v -.It Bq Er EDQUOT -The directory in which the entry for the new link -is being placed cannot be extended because the -user's quota of disk blocks on the file system -containing the directory has been exhausted. -.It Bq Er EIO -An I/O error occurred while reading from or writing to -the file system to make the directory entry. -.It Bq Er EROFS -The requested link requires writing in a directory on a read-only file -system. -.It Bq Er EFAULT -One of the pathnames specified -is outside the process's allocated address space. +.El +.Pp +In addition to the errors returned by the +.Fn link , +the +.Fn linkat +system call may fail if: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa name1 +or +.Fa name2 +argument does not specify an absolute path and the +.Fa fd1 +or +.Fa fd2 +argument, respectively, is neither +.Dv AT_FDCWD +nor a valid file descriptor open for searching. +.It Bq Er EINVAL +The value of the +.Fa flag +argument is not valid. +.It Bq Er ENOTSUP +.Fa flag +was not set to +.Dv AT_SYMLINK_FOLLOW (some filesystems only) +.It Bq Er ENOTDIR +The +.Fa name1 +or +.Fa name2 +argument is not an absolute path and +.Fa fd1 +or +.Fa fd2 , +respectively, is neither +.Dv AT_FDCWD +nor a file descriptor associated with a directory. .El .Sh SEE ALSO .Xr symlink 2 , @@ -151,3 +297,6 @@ The .Fn link function is expected to conform to .St -p1003.1-88 . +The +.Fn linkat +system call is expected to conform to POSIX.1-2008 .