Linux Certif

Toute la documentation sur la certification Linux LPI

dirname

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 for the MinGW implementation of the dirname and basename functions by Keith Marshall, <keithmarshall@users.sourceforge.net>. It may copied, modified and redistributed, without restriction of copyright, provided this acknowledgement of contribution by the original author remains unchanged.