1 .\" t

     2 .TH DIRNAME 3 04-Jan-2007 MinGW "Programmer's Reference Manual"

     3 .

     4 .SH NAME

     5 .

     6 .BR dirname ,\0 basename

     7 \- parse path name components

     8 .

     9 .

    10 .SH SYNOPSIS

    11 .

    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  );

    22 .

    23 .

    24 .SH DESCRIPTION

    25 .

    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.

    63 .

    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.

    81 .

    82 .PP

    83 If

    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.

    95 If

    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.

   113 .

   114 .PP

   115 If

   116 .I path

   117 is a NULL pointer,

   118 or is a pointer to an empty string,

   119 then both

   120 .B dirname

   121 and

   122 .B basename

   123 return the string

   124 .RB \(dq . \(dq.

   125 .

   126 .PP

   127 If

   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

   135 and

   136 .B basename

   137 return the string

   138 .RB \(dq / \(dq,

   139 or the string

   140 .RB \(dq \e \(dq,

   141 respectively.

   142 .

   143 .PP

   144 If

   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 ,

   157 if

   158 .I path

   159 includes an MS\-Windows(\(tm) drive designator.

   160 .

   161 .PP

   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

   178 or

   179 .RB \(dq \e \(dq,

   180 matching the characters used to specify

   181 .IR path .

   182 .

   183 .PP

   184 Concatenating the string returned by

   185 .BR dirname ,

   186 a

   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.

   193 .

   194 .PP

   195 The

   196 .B dirname

   197 and

   198 .B basename

   199 functions conform generally to SUSv3,

   200 extended to accommodate the handling of

   201 .RB \(dq / \(dq

   202 and

   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.

   211 .

   212 .

   213 .SH EXAMPLE

   214 .

   215 To verify the behaviour of the

   216 .B dirname

   217 and

   218 .B basename

   219 functions,

   220 the test program defines the following function:\(em

   221 .

   222 .PP

   223 .RS

   224 .nf

   225 #include <stdio.h>

   226 #include <string.h>

   227 #include <libgen.h>

   228 

   229 void result( char *path )

   230 {

   231   char *dir = strdup( path );

   232   char *file = strdup( path );

   233 

   234   printf( " %-15s%-15s%-12s", path, dirname( dir ),

   235           basename( file ) );

   236 

   237   free( dir );

   238   free( file );

   239 }

   240 .fi

   241 .RE

   242 .PP

   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.

   260 .

   261 .PP

   262 Calling this example function illustrates the effect of each of the

   263 .B dirname

   264 and

   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

   272 .RS

   273 .TS

   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..

   288 .TE

   289 .RE

   290 .

   291 .PP

   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

   297 .RS

   298 .TS

   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..

   313 .TE

   314 .RE

   315 .

   316 .PP

   317 and,

   318 when an MS\-Windows(\(tm) drive designator is also specified,

   319 this becomes:\(em

   320 .RS

   321 .TS

   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..

   336 .TE

   337 .RE

   338 .

   339 .PP

   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

   348 .RS

   349 .TS

   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

   365 .TE

   366 .RE

   367 .

   368 .

   369 .SH RETURN VALUE

   370 .

   371 The

   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.

   380 .

   381 .PP

   382 The

   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.

   390 .

   391 .PP

   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.

   401 .

   402 .

   403 .SH ERROR RETURNS

   404 .

   405 None.

   406 .

   407 .

   408 .SH CAVEATS AND BUGS

   409 .

   410 The

   411 .B dirname

   412 and

   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.

   423 .PP

   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.

   438 .PP

   439 Although the

   440 .B dirname

   441 and

   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.

   458 .

   459 .

   460 .SH AUTHOR

   461 .

   462 This manpage was written for the MinGW implementation of the

   463 .B dirname

   464 and

   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.

   472 .

   473 .

   474 .\" EOF