ReadLink

Reads the path for a soft file system link (V36)

ReadLink() takes a Lock/name pair (usually from a failed attempt to use them to access an object with packets), and asks the file system to find the softlink and fill buffer with the modified path string. You then start the resolution process again by calling GetDeviceProc() with the new string from ReadLink().

Soft-links are resolved at access time by a combination of the file system (by returning ERROR_IS_SOFT_LINK to dos.library), and by dos.library (using ReadLink() to resolve any links that are hit).

port

msgport of the file system

lock

the Lock which this path is relative to on the file system

path

path that caused the ERROR_IS_SOFT_LINK

buffer

pointer to buffer for new path from handler.

size

size of buffer.

Status

0 (FALSE) indicates failure; check IoErr(). -2 indicates that the size of the buffer supplied is too

small; you may want to increase the buffer size and try again.

-1 (DOSTRUE) indicates success, as would any value

which is neither 0 nor -2. A file system should, however always return DOSTRUE unless 0 or -2 are called for to indicate failure or the need for a larger buffer.

Soft link resolution, in particular for soft links relative to the directory in which they were found, used to be unreliable due to both implementation issues and lack of documentation on how to implement the resolution in file systems. Prior to AmigaOS 3.5 all Amiga file systems which nominally supported soft links should not be expected to support anything but soft links to absolute path names, i.e. a link to "/foo/bar" is likely not going to be resolved correctly, but a link to "foo:bar" will likely be resolved correctly.

The size of the buffer should not exceed 256 characters. While the buffer is filled with a NUL-terminated 'C' string, the dos.library file system API functions (Open(), Lock(), Rename(), Delete(), etc.) are limited to a 255 character path/file name string. If you need to increase the size of the buffer, stop before you go beyond 256 characters.

Should ReadLink() return -2, you may want to try again using a larger buffer. Keep in mind that Amiga file systems are bound to truncate path names which are longer than 255 characters. If you need to try again with a larger buffer, you may want to stop retrying with an even larger buffer when its size already exceeds 255 characters.

In V36, soft-links did not work in the ROM file systems. This was not fixed for V37 in spite of prior claims to the contrary. The use of soft links never worked consistently or reliably in the ROM file systems such as the FFS and RAM: until AmigaOS 3.1.4 (V46).

The V36-V40 ram-handler would return -2 if the resolved soft link path would exceed the size of the resolution buffer, with the minimum resolution buffer size as the secondary result. Calling IoErr() would then tell you the size to use. This feature was wholly absent in the ROM file system V36-V40 which would always return -1 upon failure, regardless of the buffer size being an issue. If you find that the ReadLink() function returns -2, you should therefore disregard the secondary result returned in IoErr() and retry with a larger buffer of your choice. Make sure that retrying the resolution with a larger buffer ceases after a few attempts or when a maximum threshold has been exceeded.

Note that the ram-handler behaviour of returning -2 and the buffer size via IoErr() was removed in ram-handler V44.

MakeLink(), Open(), Lock(), GetDeviceProc()