Debian Codegraph @

upstream/debian-unstable/man3/basename.3

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