]>
Commit | Line | Data |
---|---|---|
616c2730 | 1 | .\" Copyright (c) 2000 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 2 | .\" |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
16 | .\" the use of the information contained herein. The author(s) may not |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
c08df37a | 24 | .\" |
fea681da MK |
25 | .\" Created, 14 Dec 2000 by Michael Kerrisk |
26 | .\" | |
9ba01802 | 27 | .TH BASENAME 3 2019-03-06 "GNU" "Linux Programmer's Manual" |
fea681da | 28 | .SH NAME |
d975bcd3 | 29 | basename, dirname \- parse pathname components |
fea681da MK |
30 | .SH SYNOPSIS |
31 | .nf | |
32 | .B #include <libgen.h> | |
68e4db0a | 33 | .PP |
fea681da | 34 | .BI "char *dirname(char *" path ); |
dbfe9c70 | 35 | .PP |
fea681da MK |
36 | .BI "char *basename(char *" path ); |
37 | .fi | |
38 | .SH DESCRIPTION | |
39 | Warning: there are two different functions | |
e511ffb6 | 40 | .BR basename () |
fea681da | 41 | - see below. |
dd3568a1 | 42 | .PP |
fea681da | 43 | The functions |
e511ffb6 | 44 | .BR dirname () |
fea681da | 45 | and |
e511ffb6 | 46 | .BR basename () |
c13182ef MK |
47 | break a null-terminated pathname string into directory |
48 | and filename components. | |
49 | In the usual case, | |
e511ffb6 | 50 | .BR dirname () |
f81fb444 | 51 | returns the string up to, but not including, the final \(aq/\(aq, and |
e511ffb6 | 52 | .BR basename () |
f81fb444 MK |
53 | returns the component following the final \(aq/\(aq. |
54 | Trailing \(aq/\(aq characters are not counted as part of the pathname. | |
fea681da | 55 | .PP |
c13182ef | 56 | If |
fea681da MK |
57 | .I path |
58 | does not contain a slash, | |
e511ffb6 | 59 | .BR dirname () |
fea681da | 60 | returns the string "." while |
e511ffb6 | 61 | .BR basename () |
fea681da MK |
62 | returns a copy of |
63 | .IR path . | |
c13182ef | 64 | If |
fea681da MK |
65 | .I path |
66 | is the string "/", then both | |
e511ffb6 | 67 | .BR dirname () |
c13182ef | 68 | and |
e511ffb6 | 69 | .BR basename () |
fea681da | 70 | return the string "/". |
c13182ef | 71 | If |
fea681da | 72 | .I path |
b437fdd9 | 73 | is a null pointer or points to an empty string, then both |
e511ffb6 | 74 | .BR dirname () |
fea681da | 75 | and |
e511ffb6 | 76 | .BR basename () |
fea681da MK |
77 | return the string ".". |
78 | .PP | |
79 | Concatenating the string returned by | |
e511ffb6 | 80 | .BR dirname (), |
c13182ef | 81 | a "/", and the string returned by |
e511ffb6 | 82 | .BR basename () |
fea681da MK |
83 | yields a complete pathname. |
84 | .PP | |
c13182ef | 85 | Both |
e511ffb6 | 86 | .BR dirname () |
fea681da | 87 | and |
e511ffb6 | 88 | .BR basename () |
c13182ef MK |
89 | may modify the contents of |
90 | .IR path , | |
91 | so it may be desirable to pass a copy when calling one of | |
4fd481a3 MK |
92 | these functions. |
93 | .PP | |
94 | These functions may return pointers to statically allocated memory | |
fea681da | 95 | which may be overwritten by subsequent calls. |
4fd481a3 MK |
96 | Alternatively, they may return a pointer to some part of |
97 | .IR path , | |
98 | so that the string referred to by | |
99 | .I path | |
100 | should not be modified or freed until the pointer returned by | |
101 | the function is no longer required. | |
fea681da MK |
102 | .PP |
103 | The following list of examples (taken from SUSv2) | |
c13182ef | 104 | shows the strings returned by |
e511ffb6 | 105 | .BR dirname () |
fea681da | 106 | and |
e511ffb6 | 107 | .BR basename () |
fea681da | 108 | for different paths: |
b353ceb4 | 109 | .RS |
c6076d0e ER |
110 | .TS |
111 | lb lb lb | |
112 | l l l l. | |
113 | path dirname basename | |
114 | /usr/lib /usr lib | |
115 | /usr/ / usr | |
116 | usr . usr | |
117 | / / / | |
0e88a19e MK |
118 | \&. . . |
119 | \&.. . .. | |
c6076d0e | 120 | .TE |
b353ceb4 | 121 | .RE |
47297adb | 122 | .SH RETURN VALUE |
c13182ef | 123 | Both |
e511ffb6 | 124 | .BR dirname () |
fea681da | 125 | and |
e511ffb6 | 126 | .BR basename () |
fea681da | 127 | return pointers to null-terminated strings. |
d6922779 MK |
128 | (Do not pass these pointers to |
129 | .BR free (3).) | |
61d995d6 | 130 | .SH ATTRIBUTES |
a1eceea5 MK |
131 | For an explanation of the terms used in this section, see |
132 | .BR attributes (7). | |
133 | .TS | |
134 | allbox; | |
09c4d4dd | 135 | lbw21 lb lb |
a1eceea5 MK |
136 | l l l. |
137 | Interface Attribute Value | |
138 | T{ | |
139 | .BR basename (), | |
61d995d6 | 140 | .BR dirname () |
a1eceea5 MK |
141 | T} Thread safety MT-Safe |
142 | .TE | |
47297adb | 143 | .SH CONFORMING TO |
dbe20f30 | 144 | POSIX.1-2001, POSIX.1-2008. |
fea681da MK |
145 | .SH NOTES |
146 | There are two different versions of | |
e511ffb6 | 147 | .BR basename () |
b9764f3f | 148 | - the POSIX version described above, and the GNU version, which one gets |
fea681da | 149 | after |
207050fa MK |
150 | .PP |
151 | .in +4n | |
152 | .EX | |
b80f966b | 153 | .BR " #define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
b9764f3f | 154 | .B " #include <string.h>" |
207050fa MK |
155 | .EE |
156 | .in | |
157 | .PP | |
fea681da MK |
158 | The GNU version never modifies its argument, and returns the |
159 | empty string when | |
160 | .I path | |
161 | has a trailing slash, and in particular also when it is "/". | |
162 | There is no GNU version of | |
e511ffb6 | 163 | .BR dirname (). |
dd3568a1 | 164 | .PP |
fea681da | 165 | With glibc, one gets the POSIX version of |
e511ffb6 | 166 | .BR basename () |
a9a13a50 MK |
167 | when |
168 | .I <libgen.h> | |
169 | is included, and the GNU version otherwise. | |
fea681da | 170 | .SH BUGS |
503a47c5 MK |
171 | In the glibc implementation, |
172 | the POSIX versions of these functions modify the | |
173 | .I path | |
174 | argument, and segfault when called with a static string | |
175 | such as "/usr/". | |
847e0d88 | 176 | .PP |
fea681da | 177 | Before glibc 2.2.1, the glibc version of |
e511ffb6 | 178 | .BR dirname () |
f81fb444 | 179 | did not correctly handle pathnames with trailing \(aq/\(aq characters, |
fea681da | 180 | and generated a segfault if given a NULL argument. |
2b2581ee | 181 | .SH EXAMPLE |
7de982f8 MK |
182 | The following code snippet demonstrates the use of |
183 | .BR basename () | |
184 | and | |
185 | .BR dirname (): | |
a6e2f128 | 186 | .in +4n |
b8302363 | 187 | .EX |
2b2581ee MK |
188 | char *dirc, *basec, *bname, *dname; |
189 | char *path = "/etc/passwd"; | |
190 | ||
191 | dirc = strdup(path); | |
192 | basec = strdup(path); | |
193 | dname = dirname(dirc); | |
194 | bname = basename(basec); | |
d1a71985 | 195 | printf("dirname=%s, basename=%s\en", dname, bname); |
b8302363 | 196 | .EE |
a6e2f128 | 197 | .in |
47297adb | 198 | .SH SEE ALSO |
fea681da | 199 | .BR basename (1), |
0a4f8b7b | 200 | .BR dirname (1) |