Debian Codegraph @

upstream/debian-trixie/man3/basename.3

raw
1 '\" t
2 .\" Copyright (c) 2000 by Michael Kerrisk <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Created, 14 Dec 2000 by Michael Kerrisk
7 .\"
8 .TH basename 3 2024-06-15 "Linux man-pages 6.9.1"
9 .SH NAME
10 basename, dirname \- parse pathname components
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ", " \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <libgen.h>
17 .P
18 .BI "char *dirname(char *" path );
19 .BI "char *basename(char *" path );
20 .fi
21 .SH DESCRIPTION
22 Warning: there are two different functions
23 .BR basename ();
24 see below.
25 .P
26 The functions
27 .BR dirname ()
28 and
29 .BR basename ()
30 break a null-terminated pathname string into directory
31 and filename components.
32 In the usual case,
33 .BR dirname ()
34 returns the string up to, but not including, the final \[aq]/\[aq], and
35 .BR basename ()
36 returns the component following the final \[aq]/\[aq].
37 Trailing \[aq]/\[aq] characters are not counted as part of the pathname.
38 .P
39 If
40 .I path
41 does not contain a slash,
42 .BR dirname ()
43 returns the string "." while
44 .BR basename ()
45 returns a copy of
46 .IR path .
47 If
48 .I path
49 is the string "/", then both
50 .BR dirname ()
51 and
52 .BR basename ()
53 return the string "/".
54 If
55 .I path
56 is a null pointer or points to an empty string, then both
57 .BR dirname ()
58 and
59 .BR basename ()
60 return the string ".".
61 .P
62 Concatenating the string returned by
63 .BR dirname (),
64 a "/", and the string returned by
65 .BR basename ()
66 yields a complete pathname.
67 .P
68 Both
69 .BR dirname ()
70 and
71 .BR basename ()
72 may modify the contents of
73 .IR path ,
74 so it may be desirable to pass a copy when calling one of
75 these functions.
76 .P
77 These functions may return pointers to statically allocated memory
78 which may be overwritten by subsequent calls.
79 Alternatively, they may return a pointer to some part of
80 .IR path ,
81 so that the string referred to by
82 .I path
83 should not be modified or freed until the pointer returned by
84 the function is no longer required.
85 .P
86 The following list of examples (taken from SUSv2)
87 shows the strings returned by
88 .BR dirname ()
89 and
90 .BR basename ()
91 for different paths:
92 .RS
93 .TS
94 lb lb lb
95 l l l l.
96 path dirname basename
97 /usr/lib /usr lib
98 /usr/ / usr
99 usr . usr
100 / / /
101 \&. . .
102 \&.. . ..
103 .TE
104 .RE
105 .SH RETURN VALUE
106 Both
107 .BR dirname ()
108 and
109 .BR basename ()
110 return pointers to null-terminated strings.
111 (Do not pass these pointers to
112 .BR free (3).)
113 .SH ATTRIBUTES
114 For an explanation of the terms used in this section, see
115 .BR attributes (7).
116 .TS
117 allbox;
118 lbx lb lb
119 l l l.
120 Interface Attribute Value
121 T{
122 .na
123 .nh
124 .BR basename (),
125 .BR dirname ()
126 T} Thread safety MT-Safe
127 .TE
128 .SH VERSIONS
129 There are two different versions of
130 .BR basename ()
131 - the POSIX version described above, and the GNU version, which one gets
132 after
133 .P
134 .in +4n
135 .EX
136 .BR " #define _GNU_SOURCE" " /* See feature_test_macros(7) */"
137 .B " #include <string.h>"
138 .EE
139 .in
140 .P
141 The GNU version never modifies its argument, and returns the
142 empty string when
143 .I path
144 has a trailing slash, and in particular also when it is "/".
145 There is no GNU version of
146 .BR dirname ().
147 .P
148 With glibc, one gets the POSIX version of
149 .BR basename ()
150 when
151 .I <libgen.h>
152 is included, and the GNU version otherwise.
153 .SH STANDARDS
154 POSIX.1-2008.
155 .SH HISTORY
156 POSIX.1-2001.
157 .SH BUGS
158 In the glibc implementation,
159 the POSIX versions of these functions modify the
160 .I path
161 argument, and segfault when called with a static string
162 such as "/usr/".
163 .P
164 Before glibc 2.2.1, the glibc version of
165 .BR dirname ()
166 did not correctly handle pathnames with trailing \[aq]/\[aq] characters,
167 and generated a segfault if given a NULL argument.
168 .SH EXAMPLES
169 The following code snippet demonstrates the use of
170 .BR basename ()
171 and
172 .BR dirname ():
173 .in +4n
174 .EX
175 char *dirc, *basec, *bname, *dname;
176 char *path = "/etc/passwd";
177 \&
178 dirc = strdup(path);
179 basec = strdup(path);
180 dname = dirname(dirc);
181 bname = basename(basec);
182 printf("dirname=%s, basename=%s\[rs]n", dname, bname);
183 .EE
184 .in
185 .SH SEE ALSO
186 .BR basename (1),
187 .BR dirname (1)