diff options
Diffstat (limited to 'upstream/archlinux/man3p/dirname.3p')
| -rw-r--r-- | upstream/archlinux/man3p/dirname.3p | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/dirname.3p b/upstream/archlinux/man3p/dirname.3p new file mode 100644 index 00000000..0c6a1ae4 --- /dev/null +++ b/upstream/archlinux/man3p/dirname.3p @@ -0,0 +1,174 @@ +'\" et +.TH DIRNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.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 +dirname +\(em report the parent directory name of a file pathname +.SH SYNOPSIS +.LP +.nf +#include <libgen.h> +.P +char *dirname(char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIdirname\fR() +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. The +\fIdirname\fR() +function shall not perform pathname resolution; the result shall not be +affected by whether or not +.IR path +exists or by its file type. Trailing +.BR '/' +characters in the path that are not also leading +.BR '/' +characters shall not be counted as part of the path. +.P +If +.IR path +does not contain a +.BR '/' , +then +\fIdirname\fR() +shall return a pointer to the string +.BR \(dq.\(dq . +If +.IR path +is a null pointer or points to an empty string, +\fIdirname\fR() +shall return a pointer to the string +.BR \(dq.\(dq . +.P +The +\fIdirname\fR() +function may modify the string pointed to by +.IR path , +and may return a pointer to static storage that may then be +overwritten by a subsequent call to +\fIdirname\fR(). +.P +The +\fIdirname\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIdirname\fR() +function shall return a pointer to a string as described above. +.P +The +\fIdirname\fR() +function may modify the string pointed to by +.IR path , +and may return a pointer to internal storage. The returned pointer +might be invalidated or the storage might be overwritten by a +subsequent call to +\fIdirname\fR(). +The returned pointer might also be invalidated if the calling +thread is terminated. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following code fragment reads a pathname, changes the current +working directory to the parent directory, and opens the file. +.sp +.RS 4 +.nf + +char *path = NULL, *pathcopy; +size_t buflen = 0; +ssize_t linelen = 0; +int fd; +.P +linelen = getline(&path, &buflen, stdin); +.P +path[linelen-1] = 0; +pathcopy = strdup(path); +if (chdir(dirname(pathcopy)) < 0) { + ... +} +if ((fd = open(basename(path), O_RDONLY)) >= 0) { + ... + close (fd); +} +\&... +free (pathcopy); +free (path); +.fi +.P +.RE +.P +The EXAMPLES section of the +\fIbasename\fR() +function (see +.IR "\fIbasename\fR\^(\|)") +includes a table showing examples of the results of processing +several sample pathnames by the +\fIbasename\fR() +and +\fIdirname\fR() +functions and by the +.IR basename +and +.IR dirname +utilities. +.SH "APPLICATION USAGE" +The +\fIdirname\fR() +and +\fIbasename\fR() +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. +.P +Since the meaning of the leading +.BR \(dq//\(dq +is implementation-defined, +.IR dirname ("\c +.BR //foo ") +may return either +.BR \(dq//\(dq +or +.BR '/' +(but nothing else). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIbasename\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<libgen.h>\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIbasename\fR\^", +.IR "\fIdirname\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |