diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/readlink.3p')
-rw-r--r-- | man-pages-posix-2003/man3p/readlink.3p | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/readlink.3p b/man-pages-posix-2003/man3p/readlink.3p new file mode 100644 index 0000000..93a9483 --- /dev/null +++ b/man-pages-posix-2003/man3p/readlink.3p @@ -0,0 +1,143 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "READLINK" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" readlink +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.SH NAME +readlink \- read the contents of a symbolic link +.SH SYNOPSIS +.LP +\fB#include <unistd.h> +.br +.sp +ssize_t readlink(const char *restrict\fP \fIpath\fP\fB, char *restrict\fP +\fIbuf\fP\fB, +.br +\ \ \ \ \ \ size_t\fP \fIbufsize\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fIreadlink\fP() function shall place the contents of the symbolic +link referred to by \fIpath\fP in the buffer \fIbuf\fP +which has size \fIbufsize\fP. If the number of bytes in the symbolic +link is less than \fIbufsize\fP, the contents of the +remainder of \fIbuf\fP are unspecified. If the \fIbuf\fP argument +is not large enough to contain the link content, the first +\fIbufsize\fP bytes shall be placed in \fIbuf\fP. +.LP +If the value of \fIbufsize\fP is greater than {SSIZE_MAX}, the result +is implementation-defined. +.SH RETURN VALUE +.LP +Upon successful completion, \fIreadlink\fP() shall return the count +of bytes placed in the buffer. Otherwise, it shall return a +value of -1, leave the buffer unchanged, and set \fIerrno\fP to indicate +the error. +.SH ERRORS +.LP +The \fIreadlink\fP() function shall fail if: +.TP 7 +.B EACCES +Search permission is denied for a component of the path prefix of +\fIpath\fP. +.TP 7 +.B EINVAL +The \fIpath\fP argument names a file that is not a symbolic link. +.TP 7 +.B EIO +An I/O error occurred while reading from the file system. +.TP 7 +.B ELOOP +A loop exists in symbolic links encountered during resolution of the +\fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +The length of the \fIpath\fP argument exceeds {PATH_MAX} or a pathname +component is longer than {NAME_MAX}. +.TP 7 +.B ENOENT +A component of \fIpath\fP does not name an existing file or \fIpath\fP +is an empty string. +.TP 7 +.B ENOTDIR +A component of the path prefix is not a directory. +.sp +.LP +The \fIreadlink\fP() function may fail if: +.TP 7 +.B EACCES +Read permission is denied for the directory. +.TP 7 +.B ELOOP +More than {SYMLOOP_MAX} symbolic links were encountered during resolution +of the \fIpath\fP argument. +.TP 7 +.B ENAMETOOLONG +As a result of encountering a symbolic link in resolution of the \fIpath\fP +argument, the length of the substituted pathname +string exceeded {PATH_MAX}. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Reading the Name of a Symbolic Link +.LP +The following example shows how to read the name of a symbolic link +named \fB/modules/pass1\fP. +.sp +.RS +.nf + +\fB#include <unistd.h> +.sp + +char buf[1024]; +ssizet_t len; +\&... +if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1) + buf[len] = '\\0'; +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +Conforming applications should not assume that the returned contents +of the symbolic link are null-terminated. +.SH RATIONALE +.LP +Since IEEE\ Std\ 1003.1-2001 does not require any association of file +times with symbolic links, there is no requirement +that file times be updated by \fIreadlink\fP(). The type associated +with \fIbufsiz\fP is a \fBsize_t\fP in order to be +consistent with both the ISO\ C standard and the definition of \fIread\fP(). +The behavior +specified for \fIreadlink\fP() when \fIbufsiz\fP is zero represents +historical practice. For this case, the standard developers +considered a change whereby \fIreadlink\fP() would return the number +of non-null bytes contained in the symbolic link with the +buffer \fIbuf\fP remaining unchanged; however, since the \fBstat\fP +structure member \fIst_size\fP value can be used to +determine the size of buffer necessary to contain the contents of +the symbolic link as returned by \fIreadlink\fP(), this proposal +was rejected, and the historical practice retained. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIlstat\fP(), \fIstat\fP(), \fIsymlink\fP(), +the Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<unistd.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |