diff --git a/man2/readlink.2 b/man2/readlink.2 index e9d9b6e39..857865627 100644 --- a/man2/readlink.2 +++ b/man2/readlink.2 @@ -1,5 +1,6 @@ .\" Copyright (c) 1983, 1991 The Regents of the University of California. .\" And Copyright (C) 2011 Guillem Jover +.\" And Copyright (C) 2006, 2014 Michael Kerrisk .\" All rights reserved. .\" .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) @@ -40,14 +41,22 @@ .\" 2011-09-20, Guillem Jover : .\" Added text on dynamically allocating buffer + example program .\" -.TH READLINK 2 2013-10-26 "Linux" "Linux Programmer's Manual" +.TH READLINK 2 2014-02-21 "Linux" "Linux Programmer's Manual" .SH NAME -readlink \- read value of a symbolic link +readlink, readlinkat \- read value of a symbolic link .SH SYNOPSIS +.nf .B #include .sp .BI "ssize_t readlink(const char *" path ", char *" buf ", size_t " bufsiz ); .sp +.BR "#include " "/* Definition of AT_* constants */" +.B #include +.sp +.BI "int readlinkat(int " dirfd ", const char *" pathname , +.BI " char *" buf ", size_t " bufsiz ); +.sp +.fi .in -4n Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): @@ -59,7 +68,20 @@ Feature Test Macro Requirements for glibc (see _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED || _POSIX_C_SOURCE\ >=\ 200112L .RE +.sp +.BR readlinkat (): +.PD 0 +.ad l +.RS 4 +.TP 4 +Since glibc 2.10: +_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L +.TP +Before glibc 2.10: +_ATFILE_SOURCE +.RE .ad b +.PD .SH DESCRIPTION .BR readlink () places the contents of the symbolic link @@ -74,10 +96,61 @@ does not append a null byte to It will truncate the contents (to a length of .I bufsiz characters), in case the buffer is too small to hold all of the contents. +.SS readlinkat() +The +.BR readlinkat () +system call operates in exactly the same way as +.BR readlink (2), +except for the differences described here. + +If the pathname given in +.I pathname +is relative, then it is interpreted relative to the directory +referred to by the file descriptor +.I dirfd +(rather than relative to the current working directory of +the calling process, as is done by +.BR readlink (2) +for a relative pathname). + +If +.I pathname +is relative and +.I dirfd +is the special value +.BR AT_FDCWD , +then +.I pathname +is interpreted relative to the current working +directory of the calling process (like +.BR readlink (2)). + +If +.I pathname +is absolute, then +.I dirfd +is ignored. + +Since Linux 2.6.39, +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +.I pathname +can be an empty string, +in which case the call operates on the file referred to by +.IR dirfd +(which may have been obtained using the +.BR open (2) +.B O_PATH +flag). +In this case, +.I dirfd +can refer to any type of file, not just a directory. +.PP +See +.BR openat (2) +for an explanation of the need for +.BR readlinkat (). .SH RETURN VALUE -On success, -.BR readlink () -returns the number of bytes placed in +On success, these calls return the number of bytes placed in .IR buf . On error, \-1 is returned and .I errno @@ -122,11 +195,32 @@ Insufficient kernel memory was available. .TP .B ENOTDIR A component of the path prefix is not a directory. +.PP +The following additional errors can occur for +.BR readlinkat (): +.TP +.B EBADF +.I dirfd +is not a valid file descriptor. +.TP +.B ENOTDIR +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.SH VERSIONS +.BR readlinkat () +was added to Linux in kernel 2.6.16; +library support was added to glibc in version 2.4. .SH CONFORMING TO +.BR readlink (): 4.4BSD .RB ( readlink () first appeared in 4.2BSD), POSIX.1-2001. + +.BR readlinkat (): +POSIX.1-2008. .SH NOTES In versions of glibc up to and including glibc 2.4, the return type of .BR readlink () @@ -214,7 +308,6 @@ main(int argc, char *argv[]) .SH SEE ALSO .BR readlink (1), .BR lstat (2), -.BR readlinkat (2), .BR stat (2), .BR symlink (2), .BR path_resolution (7),