mingw/man/man3/dirname.3

   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