new for linkat(2).

man2/linkat.2

@@ -0,0 +1,134 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" This manpage is Copyright (C) 2006, Michael Kerrisk
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\" 
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\" 
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\"
+.\"
+.TH LINKAT 2 2006-04-10 "Linux 2.6.16" "Linux Programmer's Manual"
+.SH NAME
+linkat \- create a file link relative to directory file descriptors
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.sp
+.BI "int linkat(int " olddirfd ", const char *" oldpath , 
+.BI "           int " newdirfd ", const char *" newpath ", int " flags );
+.fi
+.SH DESCRIPTION
+The
+.BR linkat ()
+system call operates in exactly the same way as
+.BR link (2),
+except for the differences described in this manual page.
+
+If the pathname given in 
+.I oldpath
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.IR olddirfd 
+(rather than relative to the current working directory of 
+the calling process, as is done by
+.BR link (2)
+for a relative pathname).
+
+If the pathname given in 
+.I oldpath
+is relative and 
+.I olddirfd
+is the special value
+.BR AT_FDCWD ,
+then
+.I oldpath
+is interpreted relative to the current working 
+directory of the calling process (like
+.BR link (2)).
+
+If the pathname given in
+.IR oldpath
+is absolute, then 
+.I olddirfd 
+is ignored.
+
+The interpretation of
+.I newpath
+is as for 
+.IR oldpath , 
+except that a relative pathname is interpreted relative
+to the directory referred to by the file descriptor
+.IR newdirfd .
+
+The
+.I flags
+argument is currently unused, and must be specified as 0.
+.\" Eventually there may be an AT_SYMLINK_FOLLOW flag to cause
+.\" symbolic links in oldpath to be followed (which is what
+.\" POSIX.1 requires of link(2)).
+.\" FIXME . check whether the AT_SYMLINK_FOLLOW flag eventually 
+.\" gets implemented
+.SH "RETURN VALUE"
+On success,
+.BR linkat () 
+returns 0.  
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+The same errors that occur for
+.BR link (2)
+can also occur for
+.BR linkat ().
+The following additional errors can occur for 
+.BR linkat ():
+.TP
+.B EBADF
+.I olddirfd
+or
+.I newdirfd
+is not a valid file descriptor.
+.TP
+.B ENOTDIR
+.I oldpath
+is a relative path and
+.I olddirfd
+is a file descriptor referring to a file other than a directory;
+or similar for
+.I newpath
+and
+.IR newdirfd
+.SH NOTES
+See
+.BR openat (2)
+for an explanation of the need for
+.BR linkat ().
+.SH "CONFORMING TO"
+This system call is non-standard but is proposed
+for inclusion in a future revision of POSIX.1.
+.SH VERSIONS
+.BR linkat ()
+was added to Linux in kernel 2.6.16.
+.SH "SEE ALSO"
+.\" FIXME . add a link from link.2 to this page.
+.\" FIXME . add a link from openat.2 to this page.
+.BR link (2),
+.BR openat (2),
+.BR path_resolution (2)
+.\" FIXME . eventually list other *at.2 pages here?