summaryrefslogtreecommitdiffstats
path: root/man3/basename.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/basename.3188
1 files changed, 188 insertions, 0 deletions
diff --git a/man3/basename.3 b/man3/basename.3
new file mode 100644
index 0000000..266c49a
--- /dev/null
+++ b/man3/basename.3
@@ -0,0 +1,188 @@
+'\" 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 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+basename, dirname \- parse pathname components
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <libgen.h>
+.PP
+.BI "char *dirname(char *" path );
+.BI "char *basename(char *" path );
+.fi
+.SH DESCRIPTION
+Warning: there are two different functions
+.BR basename ();
+see below.
+.PP
+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.
+.PP
+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 ".".
+.PP
+Concatenating the string returned by
+.BR dirname (),
+a "/", and the string returned by
+.BR basename ()
+yields a complete pathname.
+.PP
+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.
+.PP
+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.
+.PP
+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
+.sp 1
+.SH VERSIONS
+There are two different versions of
+.BR basename ()
+- the POSIX version described above, and the GNU version, which one gets
+after
+.PP
+.in +4n
+.EX
+.BR " #define _GNU_SOURCE" " /* See feature_test_macros(7) */"
+.B " #include <string.h>"
+.EE
+.in
+.PP
+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 ().
+.PP
+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/".
+.PP
+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)