diff options
Diffstat (limited to 'man3/basename.3')
| -rw-r--r-- | man3/basename.3 | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/man3/basename.3 b/man3/basename.3 new file mode 100644 index 000000000..5f0629d5c --- /dev/null +++ b/man3/basename.3 @@ -0,0 +1,163 @@ +.\" (c) 2000 by Michael Kerrisk (michael.kerrisk@gmx.net) +.\" +.\" 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. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" License. +.\" Created, 14 Dec 2000 by Michael Kerrisk +.\" +.TH DIRNAME 3 2000-12-14 "GNU" "Linux Programmer's Manual" +.SH NAME +dirname, basename \- Parse pathname components +.SH SYNOPSIS +.nf +.B #include <libgen.h> +.sp +.BI "char *dirname(char *" path ); +.nl +.BI "char *basename(char *" path ); +.fi +.SH DESCRIPTION +Warning: there are two different functions +.B basename +- see below. +.LP +The functions +.B dirname +and +.B basename +break a null-terminated pathname string into directory +and filename components. +In the usual case, +.B dirname +returns the string up to, but not including, the final '/', and +.B basename +returns the component following the final '/'. +Trailing '/' characters are not counted as part of the pathname. +.PP +If +.I path +does not contain a slash, +.B dirname +returns the string "." while +.B basename +returns a copy of +.IR path . +If +.I path +is the string "/", then both +.B dirname +and +.B basename +return the string "/". +If +.I path +is a NULL pointer or points to an empty string, then both +.B dirname +and +.B basename +return the string ".". +.PP +Concatenating the string returned by +.BR dirname , +a "/", and the string returned by +.B basename +yields a complete pathname. +.PP +Both +.B dirname +and +.B basename +may modify the contents of +.IR path , +so copies should be passed to these functions. +Furthermore, +.B dirname +and +.B basename +may return pointers to statically allocated memory +which may be overwritten by subsequent calls. +.PP +The following list of examples (taken from SUSv2) +shows the strings returned by +.B dirname +and +.B basename +for different paths: +.sp +.nf +.B +path dirname basename +"/usr/lib" "/usr" "lib" +"/usr/" "/" "usr" +"usr" "." "usr" +"/" "/" "/" +"." "." "." +".." "." ".." +.fi +.SH EXAMPLE +.RS +.nf +char *dirc, *basec, *bname, *dname; +char *path = "/etc/passwd"; + +dirc = strdup(path); +basec = strdup(path); +dname = dirname(dirc); +bname = basename(basec); +printf("dirname=%s, basename=%s\\n", dname, bname); +.fi +.RE +.SH "RETURN VALUE" +Both +.B dirname +and +.B basename +return pointers to null-terminated strings. +.SH NOTES +There are two different versions of +.B basename +- the POSIX version described above, and the GNU version one gets +after +.br +.nf +.B " #define _GNU_SOURCE" +.br +.B " #include <string.h>" +.fi +The GNU version never modifies its argument, and returns the +empty string when +.I path +has a trailing slash, and in particular also when it is "/". +There is no GNU version of +.BR dirname . +.LP +With glibc, one gets the POSIX version of +.B basename +when <libgen.h> is included, and the GNU version otherwise. +.SH BUGS +In the glibc implementation of the POSIX versions of these functions +they modify their argument, and segfault when called with a static string +like "/usr/". +Before glibc 2.2.1, the glibc version of +.B dirname +did not correctly handle pathnames with trailing '/' characters, +and generated a segfault if given a NULL argument. +.SH "CONFORMING TO" +POSIX 1003.1-2001 +.SH "SEE ALSO" +.BR basename (1), +.BR dirname (1) |