From 51fa356ef2b474582711905f09dc653c3406c7b7 Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Mon, 6 Mar 2006 04:36:54 +0000
Subject: [PATCH] openat(2) is new in 2.6.16.

---
 man2/openat.2 | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++
 man2/utime.2  |   3 +-
 2 files changed, 122 insertions(+), 1 deletion(-)
 create mode 100644 man2/openat.2

diff --git a/man2/openat.2 b/man2/openat.2
new file mode 100644
index 000000000..e02a1736a
--- /dev/null
+++ b/man2/openat.2
@@ -0,0 +1,120 @@
+.\" 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 OPENAT 2 2006-03-06 "Linux 2.6.16" "Linux Programmer's Manual"
+.SH NAME
+openat \- open a file at a relative location
+.SH SYNOPSIS
+.nf
+.B #include <sys/types.h>
+.B #include <sys/stat.h>
+.B #include <fcntl.h>
+.sp
+.BI "int openat(int " dirfd ", const char *" pathname ", int " flags );
+.BI "int openat(int " dirfd ", const char *" pathname ", int " flags \
+", mode_t " mode );
+.fi
+.SH DESCRIPTION
+The
+.BR openat ()
+system call operates in exactly the same way as
+.BR open (2),
+except for the differences described in this manual page.
+
+If the pathname given in 
+.I pathname
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.IR dirfd 
+(rather than relative to the current working directory of 
+the calling process, as is done by
+.BR open (2)
+for a relative pathname).
+
+If the pathname given in 
+.I pathname
+is relative and 
+.I dirfd
+is the special value
+.BR AT_FDCWD ,
+then pathname is interpreted relative to the current working 
+directory of the calling process (like
+.BR open (2)).
+
+If the pathname given in
+.IR pathname
+is absolute, then 
+.I dirfd 
+is ignored.
+.SH "RETURN VALUE"
+.BR openat () 
+returns a new file descriptor, or \-1 if an error occurred
+(in which case,
+.I errno
+is set appropriately).
+.SH ERRORS
+The same errors that occur for
+.BR open (2)
+can also occur for
+.BR openat (2).
+The following additional errors can occur for 
+.BR openat ():
+.TP
+.B EBADF
+.I dirfd
+is not a valid file descriptor.
+.TP
+.B ENOTDIR
+.I dirfd
+is a file descriptor referring to a file other than a directory.
+.SH NOTES
+The 
+.BR openat ()
+system call (and similar system calls suffixed "at")
+provides functionality that can otherwise only be obtained 
+less efficiently or at the risk of races in user applications.
+It allows the implementation of a per-thread "current working 
+directory", via file descriptor(s) maintained by the application.
+(This functionality can also be obtained by tricks based
+on the use of
+.IR /proc/self/fd/ dirfd, 
+but less efficiently.)
+It also allows the avoidance of various kinds of races that can occur 
+as a result of directory deletions that may occur while an application 
+is traversing a file system.
+.SH "CONFORMING TO"
+This system call is non-standard.  
+A similar system call exists on Solaris.
+.\" The 'at' suffix in Solaris is actually double sensed.  It
+.\" primarily referred to "extended *at*tributes", which are
+.\" handled by Solaris' O_XATTR flag, but was also intended
+.\" to refer to the notion of "at a relative location".
+.SH VERSIONS
+.BR openat ()
+was added to Linux in kernel 2.6.16.
+.SH "SEE ALSO"
+.BR open (2),
+.BR path_resolution (2)
+.\" FIXME add SEE ALSO for openat() to open.2
diff --git a/man2/utime.2 b/man2/utime.2
index bd9043aa3..24d314c56 100644
--- a/man2/utime.2
+++ b/man2/utime.2
@@ -158,4 +158,5 @@ EINTR, ELOOP, EMULTIHOP, ENAMETOOLONG, ENOLINK, ENOLINK, ENOTDIR.
 4.3BSD
 .SH "SEE ALSO"
 .BR chattr (1),
-.BR stat (2)
+.BR stat (2),
+.BR futimes (3)