Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 187 insertions, 0 deletions

diff --git a/man/man3/basename.3 b/man/man3/basename.3
new file mode 100644
index 0000000..5d1e7fc
--- /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 2024-05-02 "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)