]>
Commit | Line | Data |
---|---|---|
c11b1abf | 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 | .\" | |
d6922779 | 27 | .TH BASENAME 3 2009-03-30 "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> | |
33 | .sp | |
34 | .BI "char *dirname(char *" path ); | |
5895e7eb | 35 | |
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 MK |
41 | - see below. |
42 | .LP | |
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 MK |
72 | .I path |
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 MK |
108 | for different paths: |
109 | .sp | |
110 | .nf | |
2fadbfb5 MK |
111 | .B "path dirname basename" |
112 | "/usr/lib" "/usr" "lib" | |
113 | "/usr/" "/" "usr" | |
114 | "usr" "." "usr" | |
115 | "/" "/" "/" | |
116 | "." "." "." | |
117 | ".." "." ".." | |
fea681da | 118 | .fi |
47297adb | 119 | .SH RETURN VALUE |
c13182ef | 120 | Both |
e511ffb6 | 121 | .BR dirname () |
fea681da | 122 | and |
e511ffb6 | 123 | .BR basename () |
fea681da | 124 | return pointers to null-terminated strings. |
d6922779 MK |
125 | (Do not pass these pointers to |
126 | .BR free (3).) | |
47297adb | 127 | .SH CONFORMING TO |
44a2c328 | 128 | POSIX.1-2001. |
fea681da MK |
129 | .SH NOTES |
130 | There are two different versions of | |
e511ffb6 | 131 | .BR basename () |
b9764f3f | 132 | - the POSIX version described above, and the GNU version, which one gets |
fea681da MK |
133 | after |
134 | .br | |
135 | .nf | |
b9764f3f | 136 | |
b80f966b | 137 | .BR " #define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
fea681da | 138 | .br |
b9764f3f MK |
139 | .B " #include <string.h>" |
140 | ||
fea681da MK |
141 | .fi |
142 | The GNU version never modifies its argument, and returns the | |
143 | empty string when | |
144 | .I path | |
145 | has a trailing slash, and in particular also when it is "/". | |
146 | There is no GNU version of | |
e511ffb6 | 147 | .BR dirname (). |
fea681da MK |
148 | .LP |
149 | With glibc, one gets the POSIX version of | |
e511ffb6 | 150 | .BR basename () |
a9a13a50 MK |
151 | when |
152 | .I <libgen.h> | |
153 | is included, and the GNU version otherwise. | |
fea681da MK |
154 | .SH BUGS |
155 | In the glibc implementation of the POSIX versions of these functions | |
156 | they modify their argument, and segfault when called with a static string | |
157 | like "/usr/". | |
158 | Before glibc 2.2.1, the glibc version of | |
e511ffb6 | 159 | .BR dirname () |
f81fb444 | 160 | did not correctly handle pathnames with trailing \(aq/\(aq characters, |
fea681da | 161 | and generated a segfault if given a NULL argument. |
2b2581ee | 162 | .SH EXAMPLE |
a6e2f128 | 163 | .in +4n |
2b2581ee MK |
164 | .nf |
165 | char *dirc, *basec, *bname, *dname; | |
166 | char *path = "/etc/passwd"; | |
167 | ||
168 | dirc = strdup(path); | |
169 | basec = strdup(path); | |
170 | dname = dirname(dirc); | |
171 | bname = basename(basec); | |
172 | printf("dirname=%s, basename=%s\\n", dname, bname); | |
173 | .fi | |
a6e2f128 | 174 | .in |
47297adb | 175 | .SH SEE ALSO |
fea681da | 176 | .BR basename (1), |
0a4f8b7b | 177 | .BR dirname (1) |