Home / Autodocs / dos.library
NAME
- SplitName
-
splits out a component of a path name into a buffer (V36)
SYNOPSIS
newpos = SplitName(pathname, separator, buffer, oldpos, size)
D0 D1 D2 D3 D4 D5
WORD SplitName(CONST_STRPTR, TEXT, STRPTR, WORD, WORD)
D0 D1 D2 D3 D4 D5
WORD SplitName(CONST_STRPTR, TEXT, STRPTR, WORD, WORD)
FUNCTION
This function splits out the next piece of a name from a given path name. Each piece is copied into the buffer, truncated to size-1 characters unless it is shorter than size characters. The position of the next piece is then returned so that it may be passed in to the next call to SplitName(). If the separator is not found within size characters, then size-1 characters will be put into the buffer, and the position of the next piece of the name will be returned.
If a separator cannot be found, then up to size-1 characters will be put into the buffer, and -1 will be returned.
When SplitName() returns, the buffer will always be NUL-terminated.
This function is mainly intended to support handlers. It has no knowledge of AmigaDOS path name semantics and will fail, for example, to correctly parse a path such as "SYS:Devs/DOSDrivers//" and split it into "SYS:", "Devs", "DOSDrivers" and "/".
If a separator cannot be found, then up to size-1 characters will be put into the buffer, and -1 will be returned.
When SplitName() returns, the buffer will always be NUL-terminated.
This function is mainly intended to support handlers. It has no knowledge of AmigaDOS path name semantics and will fail, for example, to correctly parse a path such as "SYS:Devs/DOSDrivers//" and split it into "SYS:", "Devs", "DOSDrivers" and "/".
INPUTS
- pathname
-
Path name being parsed.
- separator
-
Separator character to split by.
- buffer
-
Buffer to hold separated name.
- oldpos
-
Current position in the file; must be in the range of 0..32767
- size
-
Size of buffer in bytes, including NUL-termination; must be in the range of 1..32767.
RESULT
- newpos
-
New position for next call to SplitName(). -1 for the last piece of the path name.
WARNING
The path name must not be longer than 32767 characters.
The size of the buffer must never be smaller than 1 character and it must never be larger than 32767 characters. If you use buffer sizes outside this range, undefined behaviour will follow.
The path name to be parsed must be NUL-terminated. SplitName() will show undefined behaviour if this is not the case.
SplitName() does not indicate if the piece of the path name returned was truncated. This is a feature, not a limitation.
The size of the buffer must never be smaller than 1 character and it must never be larger than 32767 characters. If you use buffer sizes outside this range, undefined behaviour will follow.
The path name to be parsed must be NUL-terminated. SplitName() will show undefined behaviour if this is not the case.
SplitName() does not indicate if the piece of the path name returned was truncated. This is a feature, not a limitation.
BUGS
In V36 and V37, path pieces greater than or equal to size caused the last character of the piece to be lost when followed by a separator. Fixed for V39 dos.library. For V36 and V37, the suggested workaround is to call SplitName() with a buffer one larger than normal (for example, 32 bytes), and then set buffer[size-2] to 0 (for example, buffer[30] = 0;).
SplitName() will miscount the number of characters processed when truncating a piece of the path whose length exceeds the size limit if this piece ends with a separator character instead of the NUL character. In this case, SplitName() will return the correctly truncated piece, but the following piece returned will be an empty string. This bug has been present since V36.
SplitName() will miscount the number of characters processed when truncating a piece of the path whose length exceeds the size limit if this piece ends with a separator character instead of the NUL character. In this case, SplitName() will return the correctly truncated piece, but the following piece returned will be an empty string. This bug has been present since V36.