Path Name Handling

Description

When processing file names, it is often necessary to extract only a file name from a path or to generate an absolute path to a file. The dos.library contains several routines designed to make this easier.

The FilePart() function takes a pointer to a file path and returns a pointer to the last part of the string (the part of the string that follows the last separator character, "/"). The last part of the string is normally a file or directory name.

STRPTR FilePart(STRPTR mypath);

In case mypath (from the prototype above) consists only of a file or directory name (like startup-sequence, s, or libs), FilePart() returns a pointer to the start of the string (a.k.a. the same value as mypath).

The PathPart() function returns a pointer to the last character in the path string that doesn't include the file name (usually the separator character "/"):

STRPTR PathPart(STRPTR mypath);

If passed a pointer to the path string "sys:s/startup-sequence", PathPart() will return a pointer to "/startup-sequence". The application can then put a \0 where PathPart() points so that the original string has been shortened to a path part string. In case mypath (from the above prototype) is only a file name, PathPart() returns a pointer to this file name (the same value as mypath). This can confuse an application if it blindly expects PathPart() to return a path. An application should make sure the pointer PathPart() returns is not the same pointer the application passed to the function.

Both FilePart() and PathPart() consider the initial colon of an absolute path name (a path starting with a volume/device/assign name) to be a special separator character, but PathPart() will not include the colon in the string it returns a pointer to. For example, if passed the string "ram:tmpfile", PathPart() will return a pointer to the string "tmpfile".

Neither FilePart() nor PathPart() check the syntax of the path string passed to them, so if your application passes an invalid path to them, they will pass back equally invalid path fragments. Also, they do not process any of the wildcard tokens, treating them as normal characters. The following chart summarizes the possible results of the FilePart() and PathPart() functions. It assumes that the path supplied to the functions is valid.

wholepath is the path passed to FilePart() and PathPart(), pathpart is result of PathPart() and filepart is the result of FilePart().

1. If (wholepath != pathpart != filepart), then filepart points to the the file or directory name in wholepath and pathpart points to the '/' before the file or directory name in wholepath. For example:

wholepath: "ram:t/tmpfile"
Filepart: "tmpfile"
Pathpart: "/tmpfile"

wholepath: "//t/tmpfile"
Filepart: "tmpfile"
Pathpart: "/tmpfile"

2. If (wholepath != pathpart == filepart), then filepart and pathpart point to a file or a directory name preceded by a volume name or series of separator characters. For example:

wholepath: "ram:tmpfile"
Filepart: "tmpfile"
Pathpart: "tmpfile"

wholepath: "//tmpfile"
Filepart: "tmpfile"
Pathpart: "tmpfile"

3. If (wholepath == pathpart == filepart) then pathpart points to either a file or a directory name. This name is not preceded by a volume name.

wholepath: "tmpfile"
Filepart: "tmpfile"
Pathpart: "tmpfile"

4. If (pathpart[0] == 0), then path points to either "" (current directory), a series of separators ("/", "//", ":", etc.), or a volume/device name.

wholepath: "////"
Filepart: ""
Pathpart: ""

wholepath: "ram:"
Filepart: ""
Pathpart: ""

The dos.library AddPart() function lets you append a file or directory name to the end of a (relative) path, inserting any necessary separator characters:

BOOL AddPart(UBYTE *mypathname, UBYTE *myfilename, ULONG mysize);

AddPart() will add myfilename to the end of mypathname. The mysize argument indicates how large the mypathname buffer is. In case this buffer is too small, AppPart() returns FALSE and makes no changes to the buffer. If myfilename is an absolute path, it will replace the current contents of the mypathname buffer. If myfilename starts with a colon, AddPart() will generate a new path relative to the root of the volume/device in mypathname.

Another dos.library function called SplitName() makes it possible to extract individual volume/device, directory, or file names (referred to here as path components) from a path string:

int16 = SplitName(STRPTR mypathname, uint8 separatorchar, STRPTR buffer, int16 oldposition, int32 buffersize);

SplitName() searches through the string mypathname for the separator character (separatorchar from the above prototype) starting at oldposition. As it is stepping through mypathname, SplitName() copies the characters it encounters from mypathname to the buffer, terminating the resulting string with a NULL. It does not copy the separator character into the buffer. If it finds the separator character, SplitName() returns the position of the character that follows the separator character. This position can be used as the oldposition argument in subsequent calls to SplitName() to extract other path components from the same path. If SplitName() does not find another separator character, it will return -1, although it will still copy characters from mypathname to buffer. For example, if SplitName() was called with the following arguments:

mypathname = "ram:env/sys/win.pat"
separatorchar = '/'
oldposition = 8
buffersize = 10

buffer would contain the NULL terminated string "sys" and SplitName() would return a value of 12. If SplitName() was called again placing the return value of 12 into oldposition, buffer would contain the NULL terminated string "win.pat" and SplitName() would return a value of -1, as there are no separator characters in mypathname beyond the eleventh character.

If SplitName() runs out of room in the buffer, it will copy as much of the characters as it can fit (buffersize - 1) and will write a NULL into the last position in the buffer. Also, if SplitName() runs out of room in the buffer and it finds another separator character, the position it returns will not be of the character that follows the separator character. Instead, SplitName() will return the position of the actual separator character.