diff options
Diffstat (limited to 'man/man3/basename.3')
| -rw-r--r-- | man/man3/basename.3 | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/man/man3/basename.3 b/man/man3/basename.3 new file mode 100644 index 000000000..2702a05f8 --- /dev/null +++ b/man/man3/basename.3 @@ -0,0 +1,187 @@ +'\" t +.\" Copyright (c) 2000 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created, 14 Dec 2000 by Michael Kerrisk +.\" +.TH basename 3 (date) "Linux man-pages (unreleased)" +.SH NAME +basename, dirname \- parse pathname components +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <libgen.h> +.P +.BI "char *dirname(char *" path ); +.BI "char *basename(char *" path ); +.fi +.SH DESCRIPTION +Warning: there are two different functions +.BR basename (); +see below. +.P +The functions +.BR dirname () +and +.BR basename () +break a null-terminated pathname string into directory +and filename components. +In the usual case, +.BR dirname () +returns the string up to, but not including, the final \[aq]/\[aq], and +.BR basename () +returns the component following the final \[aq]/\[aq]. +Trailing \[aq]/\[aq] characters are not counted as part of the pathname. +.P +If +.I path +does not contain a slash, +.BR dirname () +returns the string "." while +.BR basename () +returns a copy of +.IR path . +If +.I path +is the string "/", then both +.BR dirname () +and +.BR basename () +return the string "/". +If +.I path +is a null pointer or points to an empty string, then both +.BR dirname () +and +.BR basename () +return the string ".". +.P +Concatenating the string returned by +.BR dirname (), +a "/", and the string returned by +.BR basename () +yields a complete pathname. +.P +Both +.BR dirname () +and +.BR basename () +may modify the contents of +.IR path , +so it may be desirable to pass a copy when calling one of +these functions. +.P +These functions may return pointers to statically allocated memory +which may be overwritten by subsequent calls. +Alternatively, they may return a pointer to some part of +.IR path , +so that the string referred to by +.I path +should not be modified or freed until the pointer returned by +the function is no longer required. +.P +The following list of examples (taken from SUSv2) +shows the strings returned by +.BR dirname () +and +.BR basename () +for different paths: +.RS +.TS +lb lb lb +l l l l. +path dirname basename +/usr/lib /usr lib +/usr/ / usr +usr . usr +/ / / +\&. . . +\&.. . .. +.TE +.RE +.SH RETURN VALUE +Both +.BR dirname () +and +.BR basename () +return pointers to null-terminated strings. +(Do not pass these pointers to +.BR free (3).) +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR basename (), +.BR dirname () +T} Thread safety MT-Safe +.TE +.SH VERSIONS +There are two different versions of +.BR basename () +- the POSIX version described above, and the GNU version, which one gets +after +.P +.in +4n +.EX +.BR " #define _GNU_SOURCE" " /* See feature_test_macros(7) */" +.B " #include <string.h>" +.EE +.in +.P +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 (). +.P +With glibc, one gets the POSIX version of +.BR basename () +when +.I <libgen.h> +is included, and the GNU version otherwise. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH BUGS +In the glibc implementation, +the POSIX versions of these functions modify the +.I path +argument, and segfault when called with a static string +such as "/usr/". +.P +Before glibc 2.2.1, the glibc version of +.BR dirname () +did not correctly handle pathnames with trailing \[aq]/\[aq] characters, +and generated a segfault if given a NULL argument. +.SH EXAMPLES +The following code snippet demonstrates the use of +.BR basename () +and +.BR dirname (): +.in +4n +.EX +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\en", dname, bname); +.EE +.in +.SH SEE ALSO +.BR basename (1), +.BR dirname (1) |