Work around MinGW mangling of "host:/path"
[msysgit/historical-msysgit.git] / mingw / man / man3 / dirname.3
blob82e1a9acc76c34a4aec3fa789407a0b6ec45e947
1 .\" t
2 .TH DIRNAME 3 04-Jan-2007 MinGW "Programmer's Reference Manual"
4 .SH NAME
6 .BR dirname ,\0 basename
7 \- parse path name components
10 .SH SYNOPSIS
12 .B  #include
13 .RB < libgen.h >
14 .PP
15 .B  char *dirname( char
16 .BI * path
17 .B  );
18 .br
19 .B  char *basename( char
20 .BI * path
21 .B  );
24 .SH DESCRIPTION
26 The
27 .B dirname
28 and
29 .B basename
30 functions parse a null\-terminated path name string,
31 and split it into its
32 .B directory name
33 and
34 .B file name
35 components.
36 Splitting is performed on the basis of the location of the
37 .B directory separator
38 characters,
39 which,
40 for this MS\-Windows(\(tm) implementation,
41 are the characters
42 .RB \(dq / \(dq
43 and
44 .RB \(dq \e \(dq,
45 each of which is interpreted as being equivalent.
46 Additionally,
47 if the
48 .I second
49 character of
50 .I path
51 is a colon
52 .RB (\(dq : \(dq),
53 the first two characters of
54 .I path
55 are interpreted as an MS\-Windows(\(tm) drive designator,
56 which will be included in the
57 .B directory name
58 component of
59 .IR path ,
60 but is never considered to form part of the
61 .B file name
62 component.
64 .PP
65 In normal usage,
66 .B dirname
67 returns a pointer to a string representing the path name component of
68 .IR path ,
69 up to but not including the rightmost directory separator,
70 while
71 .B basename
72 returns a pointer to the component following this separator.
73 Any trailing directory separators present in
74 .I path
75 are disregarded,
76 when determining the rightmost separator,
77 and, in the case of the return value from
78 .BR dirname ,
79 any internal sequences of recurring separator characters
80 are each reduced to a single such character.
82 .PP
84 .I path
85 contains no MS\-Windows(\(tm) drive designator,
86 and no directory separator character,
87 then
88 .B dirname
89 returns the string
90 .RB \(dq . \(dq,
91 and
92 .B basename
93 returns a copy of
94 .IR path.
96 .I path
97 does commence with an MS\-Windows(\(tm) drive designator,
98 but contains no directory separators,
99 then
100 .B dirname
101 returns the string
102 .RB \(dq d:. \(dq,
103 where
104 .RB \(dq d: \(dq
105 represents the drive designator,
106 while
107 .B basename
108 returns a copy of
109 .IR path ,
110 with its initial two characters,
111 (i.e.\ the drive designator),
112 deleted.
116 .I path
117 is a NULL pointer,
118 or is a pointer to an empty string,
119 then both
120 .B dirname
122 .B basename
123 return the string
124 .RB \(dq . \(dq.
128 .I path
129 is the string
130 .RB \(dq / \(dq,
131 or the string
132 .RB \(dq \e \(dq,
133 both
134 .B dirname
136 .B basename
137 return the string
138 .RB \(dq / \(dq,
139 or the string
140 .RB \(dq \e \(dq,
141 respectively.
145 .I path
146 commences with
147 .I exactly
148 two directory separator characters,
149 which must be similar,
150 then
151 .B dirname
152 will preserve these two characters in the returned path name.
153 This construct does not affect the string returned by
154 .BR basename ,
155 neither is this behaviour replicated by
156 .BR dirname ,
158 .I path
159 includes an MS\-Windows(\(tm) drive designator.
162 In the special case,
163 where
164 .I path
165 is specified as
166 .I exactly
167 two identical directory separator characters,
168 with no MS\-Windows(\(tm) drive designator,
169 and no following path name,
170 .B dirname
171 returns
172 .I path
173 unchanged;
174 .B basename
175 normalises the return string to only a single character,
176 either
177 .RB \(dq / \(dq
179 .RB \(dq \e \(dq,
180 matching the characters used to specify
181 .IR path .
184 Concatenating the string returned by
185 .BR dirname ,
187 .RB \(dq / \(dq
188 or a
189 .RB \(dq \e \(dq,
190 and the string returned by
191 .B basename
192 yields a complete path name.
196 .B dirname
198 .B basename
199 functions conform generally to SUSv3,
200 extended to accommodate the handling of
201 .RB \(dq / \(dq
203 .RB \(dq \e \(dq
204 as alternative directory separator characters,
205 and also to accommodate the likelihood of MS\-Windows(\(tm)
206 drive designators appearing in any path name specification.
207 The example,
208 which follows,
209 illustrates the conformance to SUSv3,
210 and also the effects of the extended behaviour.
213 .SH EXAMPLE
215 To verify the behaviour of the
216 .B dirname
218 .B basename
219 functions,
220 the test program defines the following function:\(em
225 #include <stdio.h>
226 #include <string.h>
227 #include <libgen.h>
229 void result( char *path )
231   char *dir = strdup( path );
232   char *file = strdup( path );
234   printf( " %-15s%-15s%-12s", path, dirname( dir ),
235           basename( file ) );
237   free( dir );
238   free( file );
243 This illustrates the correct use of the
244 .B dirname
245 and the
246 .B basename
247 functions,
248 with copies of the original
249 .I path
250 string being passed in the function calls.
251 Note that the return values from each function are used immediately,
252 in the
253 .B printf
254 call,
255 and the temporary copies of
256 .I path
257 are discarded,
258 and the associated memory is freed,
259 before these go out of scope.
262 Calling this example function illustrates the effect of each of the
263 .B dirname
265 .B basename
266 functions,
267 for various values of
268 .IR path .
269 The following,
270 taken from SUSv3,
271 illustrate general conformance with the standard:\(em
274 tab(!);
275 lB      lB      lB
276 lw(15n) lw(10n) lw(10n).
277 \0path!\0dirname!\0basename
278 \_!\_!\_
279 \0/usr/lib!\0/usr!\0lib
280 \0//usr//lib//!\0//usr!\0lib
281 \0///usr//lib//!\0/usr!\0lib
282 \0/usr/!\0/!\0usr
283 \0usr!\0.!\0usr
284 \0//!\0//!\0/
285 \0/!\0/!\0/
286 \0.!\0.!\0.
287 \0..!\0.!\0..
292 Similarly,
293 for the case where path names are expressed using the MS\-Windows(\(tm)
294 .RB \(dq \e \(dq
295 directory separator notation,
296 calling the example function displays:\(em
299 tab(!);
300 lB      lB      lB
301 lw(15n) lw(10n) lw(10n).
302 \0path!\0dirname!\0basename
303 \_!\_!\_
304 \0\eusr\elib!\0\eusr!\0lib
305 \0\e\eusr\e\elib\e\e!\0\e\eusr!\0lib
306 \0\e\e\eusr\e\elib\e\e!\0\eusr!\0lib
307 \0\eusr\e!\0\e!\0usr
308 \0usr!\0.!\0usr
309 \0\e\e!\0\e\e!\0\e
310 \0\e!\0\e!\0\e
311 \0.!\0.!\0.
312 \0..!\0.!\0..
317 and,
318 when an MS\-Windows(\(tm) drive designator is also specified,
319 this becomes:\(em
322 tab(!);
323 lB      lB      lB
324 lw(15n) lw(10n) lw(10n).
325 \0path!\0dirname!\0basename
326 \_!\_!\_
327 \0d:\eusr\elib!\0d:\eusr!\0lib
328 \0d:\e\eusr\e\elib\e\e!\0d:\eusr!\0lib
329 \0d:\e\e\eusr\e\elib\e\e!\0d:\eusr!\0lib
330 \0d:\eusr\e!\0d:\e!\0usr
331 \0d:usr!\0d:.!\0usr
332 \0d:\e\e!\0d:\e!\0\e
333 \0d:\e!\0d:\e!\0\e
334 \0d:.!\0d:.!\0.
335 \0d:..!\0d:.!\0..
340 Please note,
341 in particular,
342 the special handling of path names which begin with
343 .I exactly
344 two directory separator characters,
345 and also that this special handling is suppressed
346 when these two characters are dissimilar,
347 or when an MS\-Windows(\(tm) drive designator is specified:\(em
350 tab(!);
351 lB      lB      lB
352 lw(15n) lw(10n) lw(10n).
353 \0path!\0dirname!\0basename
354 \_!\_!\_
355 \0//usr//lib//!\0//usr!\0lib
356 \0\e\eusr\e\elib\e\e!\0\e\eusr!\0lib
357 \0/\eusr\e\elib\e\e!\0/usr!\0lib
358 \0\e/usr\e\elib\e\e!\0\eusr!\0lib
359 \0d:\e\eusr\e\elib\e\e!\0d:\eusr!\0lib
360 \0//!\0//!\0/
361 \0\e\e!\0\e\e!\0\e
362 \0/\e!\0/!\0/
363 \0\e/!\0\e!\0\e
364 \0d:\e\e!\0d:\e!\0\e
369 .SH RETURN VALUE
372 .B dirname
373 function returns a pointer to a null terminated string,
374 which represents the directory path component of the passed
375 .I path
376 string,
377 without any trailing directory separator character,
378 and with all internal sequences of directory separator characters
379 normalised to a single separator at each level of directory nesting.
383 .B basename
384 function
385 returns a pointer to a null terminated string,
386 which represents the rightmost element of the passed
387 .I path
388 string,
389 with all trailing directory separator characters removed.
392 If any MS\-Windows(\(tm) drive designator is specified in the input
393 .I path
394 string,
395 it is included in the return value of the
396 .B dirname
397 function,
398 but not in that of the
399 .B basename
400 function.
403 .SH ERROR RETURNS
405 None.
408 .SH CAVEATS AND BUGS
411 .B dirname
413 .B basename
414 functions may modify the
415 .I path
416 string passed to them.
417 Therefore, it is an error to pass a character constant as the
418 .I path
419 parameter;
420 to do so may result in memory violation errors,
421 (segmentation faults),
422 and consequent abnormal program termination.
424 Also note that,
425 since the
426 .I path
427 argument may be modified by the
428 .B dirname
429 or the
430 .B basename
431 function call,
432 if you wish to preserve the original content of
433 .IR path ,
434 you should pass a copy to the function.
435 Furthermore,
436 either function may return its result in a statically allocated buffer,
437 which may be overwritten on a subsequent function call.
439 Although the
440 .B dirname
442 .B basename
443 functions parse path name strings,
444 they are basically just
445 .I string
446 functions.
447 The presence of an MS\-Windows(\(tm) drive designator is determined
448 by the appearance of a colon
449 .RB (\(dq : \(dq)
450 as the second character of the
451 .I path
452 string,
453 but neither function performs any check
454 to ensure that the first character represents a valid file system device;
455 neither is any form of validation performed,
456 to ensure that the remainder of the string
457 represents a valid path name.
460 .SH AUTHOR
462 This manpage was written for the MinGW implementation of the
463 .B dirname
465 .B basename
466 functions by Keith\ Marshall,
467 <keithmarshall@users.sourceforge.net>.
468 It may copied, modified and redistributed,
469 without restriction of copyright,
470 provided this acknowledgement of contribution by
471 the original author remains unchanged.
474 .\" EOF