%PAGEREF%(MinGW)

NAME
dirname, basename - parse path name components

SYNOPSIS
#include <libgen.h>

char *dirname( char *path );
char *basename( char *path );

DESCRIPTION
The dirname() and basename() functions parse a null-terminated path name string, and split it into its directory name and file name components. Splitting is performed on the basis of the location of the directory separator characters, which, for this MS-Windows implementation, are the characters "/" and "\", each of which is interpreted as being equivalent. Additionally, if the second character of path is a colon (":"), the first two characters of path are interpreted as an MS-Windows drive designator, which will be included in the directory name component of path, but is never considered to form part of the file name component.

In normal usage, dirname() returns a pointer to a string representing the path name component of path, up to but not including the rightmost directory separator, while basename() returns a pointer to the component following this separator. Any trailing directory separators present in path are disregarded, when determining the rightmost separator, and, in the case of the return value from dirname(), any internal sequences of recurring separator characters are each reduced to a single such character.

If path contains no MS-Windows drive designator, and no directory separator character, then dirname() returns the string ".", and basename() returns a copy of path. If path does commence with an MS-Windows drive designator, but contains no directory separators, then dirname() returns the string "d:.", where "d:" represents the drive designator, while basename() returns a copy of path, with its initial two characters, (i.e. the drive designator), deleted.

If path is a NULL pointer, or is a pointer to an empty string, then both dirname() and basename() return the string ".".

If path is the string "/", or the string "\", both dirname() and basename() return the string "/", or the string "\", respectively.

If path commences with exactly two directory separator characters, which must be similar, then dirname() will preserve these two characters in the returned path name. This construct does not affect the string returned by basename(), neither is this behaviour replicated by dirname(), if path includes an MS-Windows drive designator.

In the special case, where path is specified as exactly two identical directory separator characters, with no MS-Windows drive designator, and no following path name, dirname() returns path unchanged; basename() normalises the return string to only a single character, either "/" or "\", matching the characters used to specify path.

Concatenating the string returned by dirname(), a "/" or a "\", and the string returned by basename() yields a complete path name.

The dirname() and basename() functions conform generally to SUSv3, extended to accommodate the handling of "/" and "\" as alternative directory separator characters, and also to accommodate the likelihood of MS-Windows drive designators appearing in any path name specification. The example, which follows, illustrates the conformance to SUSv3, and also the effects of the extended behaviour.

EXAMPLE
To verify the behaviour of the dirname() and basename() functions, the test program defines the following function:—

    #include <stdio.h>
    #include <string.h>
    #include <libgen.h>
    void result( char *path )
    {
      char *dir = strdup( path );
      char *file = strdup( path );
      printf( " %-15s%-15s%-12s", path, dirname( dir ),
              basename( file ) );
      free( dir );
      free( file );
    }

This illustrates the correct use of the dirname() and the basename() functions, with copies of the original path string being passed in the function calls. Note that the return values from each function are used immediately, in the printf() call, and the temporary copies of path are discarded, and the associated memory is freed, before these go out of scope.

Calling this example function illustrates the effect of each of the dirname() and basename() functions, for various values of path. The following, taken from SUSv3, illustrate general conformance with the standard:—
    path | dirname | basename
    /usr/lib | /usr | lib
    //usr//lib// | //usr | lib
    ///usr//lib// | /usr | lib
    /usr/ | / | usr
    usr | . | usr
    // | // | /
    / | / | /
    . | . | .
    .. | . | ..

Similarly, for the case where path names are expressed using the MS-Windows "\" directory separator notation, calling the example function displays:—
    path | dirname | basename
    \usr\lib | \usr | lib
    \\usr\\lib\\ | \\usr | lib
    \\\usr\\lib\\ | \usr | lib
    \usr\ | \ | usr
    usr | . | usr
    \\ | \\ | \
    \ | \ | \
    . | . | .
    .. | . | ..

and, when an MS-Windows drive designator is also specified, this becomes:—
    path | dirname | basename
    d:\usr\lib | d:\usr | lib
    d:\\usr\\lib\\ | d:\usr | lib
    d:\\\usr\\lib\\ | d:\usr | lib
    d:\usr\ | d:\ | usr
    d:usr | d:. | usr
    d:\\ | d:\ | \
    d:\ | d:\ | \
    d:. | d:. | .
    d:.. | d:. | ..

Please note, in particular, the special handling of path names which begin with exactly two directory separator characters, and also that this special handling is suppressed when these two characters are dissimilar, or when an MS-Windows drive designator is specified:—
    path | dirname | basename
    //usr//lib// | //usr | lib
    \\usr\\lib\\ | \\usr | lib
    /\usr\\lib\\ | /usr | lib
    \/usr\\lib\\ | \usr | lib
    d:\\usr\\lib\\ | d:\usr | lib
    // | // | /
    \\ | \\ | \
    /\ | / | /
    \/ | \ | \
    d:\\ | d:\ | \

RETURN VALUE
The dirname() function returns a pointer to a null terminated string, which represents the directory path component of the passed path string, without any trailing directory separator character, and with all internal sequences of directory separator characters normalised to a single separator at each level of directory nesting.

The basename() function returns a pointer to a null terminated string, which represents the rightmost element of the passed path string, with all trailing directory separator characters removed.

If any MS-Windows drive designator is specified in the input path string, it is included in the return value of the dirname() function, but not in that of the basename() function.

ERROR RETURNS
None.

CAVEATS AND BUGS
The dirname() and basename() functions may modify the path string passed to them. Therefore, it is an error to pass a character constant as the path parameter; to do so may result in memory violation errors, (segmentation faults), and consequent abnormal program termination.

Also note that, since the path argument may be modified by the dirname() or the basename() function call, if you wish to preserve the original content of path, you should pass a copy to the function. Furthermore, either function may return its result in a statically allocated buffer, which may be overwritten on a subsequent function call.

Although the dirname() and basename() functions parse path name strings, they are basically just string functions. The presence of an MS-Windows drive designator is determined by the appearance of a colon (":") as the second character of the path string, but neither function performs any check to ensure that the first character represents a valid file system device; neither is any form of validation performed, to ensure that the remainder of the string represents a valid path name.

AUTHOR
This manpage was written by Keith Marshall, <keithmarshall@users.sourceforge.net>, to document the basename() and dirname() functions as they have been implemented for the MinGW.org Project. It may be copied, modified and redistributed, without restriction of copyright, provided this acknowledgement of contribution by the original author remains unchanged.