xnu-2782.30.5.tar.gz

[apple/xnu.git] / bsd / man / man2 / link.2

diff --git a/bsd/man/man2/link.2 b/bsd/man/man2/link.2
index 6392e7ceacabd8aa64eb1409a5a28a550ddea1b9..35010cab7b0439bf3ad4fcd4fb0f8279d676c889 100644 (file)
--- a/bsd/man/man2/link.2
+++ b/bsd/man/man2/link.2
@@ -33,11 +33,12 @@
 .\"
 .\"     @(#)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 <unistd.h>
@@ -46,6 +47,10 @@
 .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
@@ -81,6 +86,84 @@ must be in the same file system.
 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
@@ -135,12 +218,12 @@ characters, or an entire path name exceeded
 characters.
 .\" ==========
 .It Bq Er ENOENT
-A component of either path prefix does not exist.
+A component of either path prefix does not exist, or is a dangling symbolic link.
 .\" ==========
 .It Bq Er ENOENT
 The file named by
 .Fa path1
-does not exist.
+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
@@ -166,6 +249,46 @@ and the file named by
 .Fa path1
 are on different file systems.
 .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 ,
 .Xr unlink 2
@@ -174,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 .