diff options
Diffstat (limited to 'man3p/dirname.3p')
| -rw-r--r-- | man3p/dirname.3p | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/man3p/dirname.3p b/man3p/dirname.3p new file mode 100644 index 000000000..f55e878d2 --- /dev/null +++ b/man3p/dirname.3p @@ -0,0 +1,136 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "DIRNAME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" dirname +.SH NAME +dirname \- report the parent directory name of a file pathname +.SH SYNOPSIS +.LP +\fB#include <libgen.h> +.br +.sp +char *dirname(char *\fP\fIpath\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIdirname\fP() function shall take a pointer to a character string +that contains a pathname, and return a pointer to a +string that is a pathname of the parent directory of that file. Trailing +\fB'/'\fP characters in the path are not counted as +part of the path. +.LP +If \fIpath\fP does not contain a \fB'/'\fP , then \fIdirname\fP() +shall return a pointer to the string \fB"."\fP . If +\fIpath\fP is a null pointer or points to an empty string, \fIdirname\fP() +shall return a pointer to the string \fB"."\fP +\&. +.LP +The \fIdirname\fP() function need not be reentrant. A function that +is not required to be reentrant is not required to be +thread-safe. +.SH RETURN VALUE +.LP +The \fIdirname\fP() function shall return a pointer to a string that +is the parent directory of \fIpath\fP. If \fIpath\fP is +a null pointer or points to an empty string, a pointer to a string +\fB"."\fP is returned. +.LP +The \fIdirname\fP() function may modify the string pointed to by \fIpath\fP, +and may return a pointer to static storage that +may then be overwritten by subsequent calls to \fIdirname\fP(). +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +The following code fragment reads a pathname, changes the current +working directory to the parent directory, and opens the +file. +.sp +.RS +.nf + +\fBchar path[PATH_MAX], *pathcopy; +int fd; +fgets(path, PATH_MAX, stdin); +pathcopy = strdup(path); +chdir(dirname(pathcopy)); +fd = open(basename(path), O_RDONLY); +\fP +.fi +.RE +.SS Sample Input and Output Strings for dirname() +.LP +In the following table, the input string is the value pointed to by +\fIpath\fP, and the output string is the return value of +the \fIdirname\fP() function. +.TS C +center; l l. +\fBInput String\fP \fBOutput String\fP +"/usr/lib" "/usr" +"/usr/" "/" +"usr" "." +"/" "/" +"." "." +".." "." +.TE +.SS Changing the Current Directory to the Parent Directory +.LP +The following program fragment reads a pathname, changes the current +working directory to the parent directory, and opens the +file. +.sp +.RS +.nf + +\fB#include <unistd.h> +#include <limits.h> +#include <stdio.h> +#include <fcntl.h> +#include <string.h> +#include <libgen.h> +\&... +char path[PATH_MAX], *pathcopy; +int fd; +\&... +fgets(path, PATH_MAX, stdin); +pathcopy = strdup(path); +chdir(dirname(pathcopy)); +fd = open(basename(path), O_RDONLY); +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +The \fIdirname\fP() and \fIbasename\fP() functions together yield +a complete +pathname. The expression \fIdirname\fP(\fIpath\fP) obtains the pathname +of the directory where \fIbasename\fP(\fIpath\fP) is +found. +.LP +Since the meaning of the leading \fB"//"\fP is implementation-defined, +\fIdirname\fP(" \fB//foo\fP) may return either +\fB"//"\fP or \fB'/'\fP (but nothing else). +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbasename\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI<libgen.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 . |