diff options
Diffstat (limited to 'winsup/mingw/man/dirname.man')
| -rwxr-xr-x | winsup/mingw/man/dirname.man | 474 |
1 files changed, 0 insertions, 474 deletions
diff --git a/winsup/mingw/man/dirname.man b/winsup/mingw/man/dirname.man deleted file mode 100755 index 82e1a9acc..000000000 --- a/winsup/mingw/man/dirname.man +++ /dev/null @@ -1,474 +0,0 @@ -.\" t -.TH DIRNAME 3 04-Jan-2007 MinGW "Programmer's Reference Manual" -. -.SH NAME -. -.BR dirname ,\0 basename -\- parse path name components -. -. -.SH SYNOPSIS -. -.B #include -.RB < libgen.h > -.PP -.B char *dirname( char -.BI * path -.B ); -.br -.B char *basename( char -.BI * path -.B ); -. -. -.SH DESCRIPTION -. -The -.B dirname -and -.B basename -functions parse a null\-terminated path name string, -and split it into its -.B directory name -and -.B file name -components. -Splitting is performed on the basis of the location of the -.B directory separator -characters, -which, -for this MS\-Windows(\(tm) implementation, -are the characters -.RB \(dq / \(dq -and -.RB \(dq \e \(dq, -each of which is interpreted as being equivalent. -Additionally, -if the -.I second -character of -.I path -is a colon -.RB (\(dq : \(dq), -the first two characters of -.I path -are interpreted as an MS\-Windows(\(tm) drive designator, -which will be included in the -.B directory name -component of -.IR path , -but is never considered to form part of the -.B file name -component. -. -.PP -In normal usage, -.B dirname -returns a pointer to a string representing the path name component of -.IR path , -up to but not including the rightmost directory separator, -while -.B basename -returns a pointer to the component following this separator. -Any trailing directory separators present in -.I path -are disregarded, -when determining the rightmost separator, -and, in the case of the return value from -.BR dirname , -any internal sequences of recurring separator characters -are each reduced to a single such character. -. -.PP -If -.I path -contains no MS\-Windows(\(tm) drive designator, -and no directory separator character, -then -.B dirname -returns the string -.RB \(dq . \(dq, -and -.B basename -returns a copy of -.IR path. -If -.I path -does commence with an MS\-Windows(\(tm) drive designator, -but contains no directory separators, -then -.B dirname -returns the string -.RB \(dq d:. \(dq, -where -.RB \(dq d: \(dq -represents the drive designator, -while -.B basename -returns a copy of -.IR path , -with its initial two characters, -(i.e.\ the drive designator), -deleted. -. -.PP -If -.I path -is a NULL pointer, -or is a pointer to an empty string, -then both -.B dirname -and -.B basename -return the string -.RB \(dq . \(dq. -. -.PP -If -.I path -is the string -.RB \(dq / \(dq, -or the string -.RB \(dq \e \(dq, -both -.B dirname -and -.B basename -return the string -.RB \(dq / \(dq, -or the string -.RB \(dq \e \(dq, -respectively. -. -.PP -If -.I path -commences with -.I exactly -two directory separator characters, -which must be similar, -then -.B dirname -will preserve these two characters in the returned path name. -This construct does not affect the string returned by -.BR basename , -neither is this behaviour replicated by -.BR dirname , -if -.I path -includes an MS\-Windows(\(tm) drive designator. -. -.PP -In the special case, -where -.I path -is specified as -.I exactly -two identical directory separator characters, -with no MS\-Windows(\(tm) drive designator, -and no following path name, -.B dirname -returns -.I path -unchanged; -.B basename -normalises the return string to only a single character, -either -.RB \(dq / \(dq -or -.RB \(dq \e \(dq, -matching the characters used to specify -.IR path . -. -.PP -Concatenating the string returned by -.BR dirname , -a -.RB \(dq / \(dq -or a -.RB \(dq \e \(dq, -and the string returned by -.B basename -yields a complete path name. -. -.PP -The -.B dirname -and -.B basename -functions conform generally to SUSv3, -extended to accommodate the handling of -.RB \(dq / \(dq -and -.RB \(dq \e \(dq -as alternative directory separator characters, -and also to accommodate the likelihood of MS\-Windows(\(tm) -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. -. -. -.SH EXAMPLE -. -To verify the behaviour of the -.B dirname -and -.B basename -functions, -the test program defines the following function:\(em -. -.PP -.RS -.nf -#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 ); -} -.fi -.RE -.PP -This illustrates the correct use of the -.B dirname -and the -.B basename -functions, -with copies of the original -.I path -string being passed in the function calls. -Note that the return values from each function are used immediately, -in the -.B printf -call, -and the temporary copies of -.I path -are discarded, -and the associated memory is freed, -before these go out of scope. -. -.PP -Calling this example function illustrates the effect of each of the -.B dirname -and -.B basename -functions, -for various values of -.IR path . -The following, -taken from SUSv3, -illustrate general conformance with the standard:\(em -.RS -.TS -tab(!); -lB lB lB -lw(15n) lw(10n) lw(10n). -\0path!\0dirname!\0basename -\_!\_!\_ -\0/usr/lib!\0/usr!\0lib -\0//usr//lib//!\0//usr!\0lib -\0///usr//lib//!\0/usr!\0lib -\0/usr/!\0/!\0usr -\0usr!\0.!\0usr -\0//!\0//!\0/ -\0/!\0/!\0/ -\0.!\0.!\0. -\0..!\0.!\0.. -.TE -.RE -. -.PP -Similarly, -for the case where path names are expressed using the MS\-Windows(\(tm) -.RB \(dq \e \(dq -directory separator notation, -calling the example function displays:\(em -.RS -.TS -tab(!); -lB lB lB -lw(15n) lw(10n) lw(10n). -\0path!\0dirname!\0basename -\_!\_!\_ -\0\eusr\elib!\0\eusr!\0lib -\0\e\eusr\e\elib\e\e!\0\e\eusr!\0lib -\0\e\e\eusr\e\elib\e\e!\0\eusr!\0lib -\0\eusr\e!\0\e!\0usr -\0usr!\0.!\0usr -\0\e\e!\0\e\e!\0\e -\0\e!\0\e!\0\e -\0.!\0.!\0. -\0..!\0.!\0.. -.TE -.RE -. -.PP -and, -when an MS\-Windows(\(tm) drive designator is also specified, -this becomes:\(em -.RS -.TS -tab(!); -lB lB lB -lw(15n) lw(10n) lw(10n). -\0path!\0dirname!\0basename -\_!\_!\_ -\0d:\eusr\elib!\0d:\eusr!\0lib -\0d:\e\eusr\e\elib\e\e!\0d:\eusr!\0lib -\0d:\e\e\eusr\e\elib\e\e!\0d:\eusr!\0lib -\0d:\eusr\e!\0d:\e!\0usr -\0d:usr!\0d:.!\0usr -\0d:\e\e!\0d:\e!\0\e -\0d:\e!\0d:\e!\0\e -\0d:.!\0d:.!\0. -\0d:..!\0d:.!\0.. -.TE -.RE -. -.PP -Please note, -in particular, -the special handling of path names which begin with -.I exactly -two directory separator characters, -and also that this special handling is suppressed -when these two characters are dissimilar, -or when an MS\-Windows(\(tm) drive designator is specified:\(em -.RS -.TS -tab(!); -lB lB lB -lw(15n) lw(10n) lw(10n). -\0path!\0dirname!\0basename -\_!\_!\_ -\0//usr//lib//!\0//usr!\0lib -\0\e\eusr\e\elib\e\e!\0\e\eusr!\0lib -\0/\eusr\e\elib\e\e!\0/usr!\0lib -\0\e/usr\e\elib\e\e!\0\eusr!\0lib -\0d:\e\eusr\e\elib\e\e!\0d:\eusr!\0lib -\0//!\0//!\0/ -\0\e\e!\0\e\e!\0\e -\0/\e!\0/!\0/ -\0\e/!\0\e!\0\e -\0d:\e\e!\0d:\e!\0\e -.TE -.RE -. -. -.SH RETURN VALUE -. -The -.B dirname -function returns a pointer to a null terminated string, -which represents the directory path component of the passed -.I 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. -. -.PP -The -.B basename -function -returns a pointer to a null terminated string, -which represents the rightmost element of the passed -.I path -string, -with all trailing directory separator characters removed. -. -.PP -If any MS\-Windows(\(tm) drive designator is specified in the input -.I path -string, -it is included in the return value of the -.B dirname -function, -but not in that of the -.B basename -function. -. -. -.SH ERROR RETURNS -. -None. -. -. -.SH CAVEATS AND BUGS -. -The -.B dirname -and -.B basename -functions may modify the -.I path -string passed to them. -Therefore, it is an error to pass a character constant as the -.I path -parameter; -to do so may result in memory violation errors, -(segmentation faults), -and consequent abnormal program termination. -.PP -Also note that, -since the -.I path -argument may be modified by the -.B dirname -or the -.B basename -function call, -if you wish to preserve the original content of -.IR 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. -.PP -Although the -.B dirname -and -.B basename -functions parse path name strings, -they are basically just -.I string -functions. -The presence of an MS\-Windows(\(tm) drive designator is determined -by the appearance of a colon -.RB (\(dq : \(dq) -as the second character of the -.I 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. -. -. -.SH AUTHOR -. -This manpage was written for the MinGW implementation of the -.B dirname -and -.B 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. -. -. -.\" EOF |