Examine

Examine a directory or file associated with a Lock

Examine() fills in information in the FileInfoBlock concerning the file, directory or link associated with the Lock. This information includes the name, size, creation date and whether it is a file, directory or a link, as well as other metadata associated with it.

Examine() is not limited to querying information about directories and directory entries. It is also used for obtaining information about all the entries within a volume or directory. You start by calling Examine() on a Lock associated with a directory or volume and then repeatedly call ExNext() until it returns an error. Each successful invocation of ExNext() will return another set of metadata for a file, directory or link stored within that directory.

The pointer to the FileInfoBlock MUST be longword aligned, i.e. the address must be divisible by 4 (== sizeof(LONG)).

You may make a local copy of the FileInfoBlock, as long as it is never passed to ExNext().

lock

BCPL pointer to a Lock

infoBlock

pointer to a FileInfoBlock (MUST be longword aligned)

success

boolean; FALSE indicates failure; call IoErr() to find out why Examine() failed.

Both Examine() and ExNext(), as well as ExamineFH() make use of the FileInfoBlock structure, as defined in the <dos/dos.h> header file. It looks as follows:

The structure members serve the following purposes:

fib_DiskKey (LONG)

The file system will store meaningful information in this field which for a disk-based storage medium is typically the unique block number under which the metadata describing this directory entry may be found. Other file systems may store less useful information here which is for its internal use only.

You may want to ignore the fib_DiskKey value because there is no general rule on what you may find here. Do not expect or depend upon the fib_DiskKey value to be unique or consistent. For example, two Locks obtained for the same directory entry may not share the same fib_DiskKey value. This is why the SameLock() function is needed to answer whether two Locks are referring to the same object.

fib_DirEntryType (LONG)

see below.

fib_EntryType (LONG)

Both fields contain identical information about the type of directory entry found. For reasons of compatibility with old operating system and application software, both field names were preserved in subsequent operating system revisions.

There is no reason why you should prefer fib_EntryType over fib_DirEntryType, or the other way round. It does help if you make a choice to use just one of these two in your own code.

The directory entry type will be one of the following (see) the <dos/dosextens.h> header file):

ST_ROOT

This is the root directory of a file system, not a user-created directory which could be deleted.

ST_USERDIR

This is a user-created directory which can be deleted, as opposed to the root directory of the file system.

ST_SOFTLINK

This is a soft link to a directory entry. It may reference a file, directory, another soft link or even a directory entry found on another volume.

ST_LINKDIR

This is a hard link to a user directory on the same volume.

ST_FILE

This is a file.

ST_LINKFILE

This is a hard link to a file on the same volume.

ST_PIPEFILE

This is a special type of file whose properties some handlers may allow you to query, e.g. the PIPE: device.

As a general rule, the directory entry types fall into two broad categories. The types with positive numbers used to be directories and the types with negative numbers used to be files. This general rule worked in Kickstart 1.2/1.3 (V33/V34), up until the introduction of soft links in Kickstart 2.0 (V36). If you examine the type of a directory entry, always check first if the type is ST_SOFTLINK. If it is not a soft link, you can check if the type is positive (a directory) or negative (a file).

fib_FileName

('C' string with room for 107 characters and '\0') The name of a directory or directory entry, such as a file or link. The length of the name cannot exceed 107 characters and the name is always terminated by a '\0' character.

Prior to the FFS and ram-handler V46 in AmigaOS 3.1.4, directory and directory entry names would rarely be longer than 30 characters, which is the upper limit for the V33-V45 Amiga ROM file system and ram-handler.

fib_Protection (LONG)

This field contains 32 bits of which the most significant 16 are currently reserved for the operating system's use. File systems make use of bits #0..#15 (inclusive). The bits have the following respective purposes:

Note:

Bits #0..#4 (inclusive) have been supported since Kickstart 1.2 (V33).

Note:

Bits #5..#7 (inclusive) have been supported since Kickstart 1.3 (V34).

Note:

Bits #8..#15 (inclusive) were reserved for use for the "Envoy" network file system but were never used as a general operating system feature. The Commodore "Envoy" product was under active development between 1992-1994 but never saw a release as a commercial product until after Commodore had gone out of business.

FIBB_DELETE

(bit #0) If set, directory entry is protected from deletion.

FIBB_EXECUTE

(bit #1) If set, directory entry cannot be used as an executable shell command or Workbench tool. This usually works only for files and has no meaning for directories.

FIBB_WRITE

(bit #2) If set, write access to this directory entry will be denied. This usually works only for files and has no meaning for directories.

FIBB_READ

(bit #3) If set, read access to this directory entry will be denied. This usually works only for files and has no meaning for directories.

FIBB_ARCHIVE

(bit #4) This bit will be cleared whenever this directory entry was modified, such as by overwriting it or changing the contents of a directory. A program which makes backups of an Amiga file system can set this bit after it has successfully backed up the associated directory and for the next backup operation determine which entries were modified since the previous backup.

FIBB_PURE

(bit #5) An executable program file which has this bit set can be loaded into memory by the shell using the "Resident" shell command. It is assumed that this program is "reentrant", meaning that executing it does not result in it modifying its own program code or its program data when it is active. This property makes it unnecessary to reload the program from disk every time it needs to be executed.

FIBB_SCRIPT

(bit #6) A file which has this bit set is a script file, such as is processed by the Execute shell command. If found, the shell will automatically invoke the "Execute" command for the script file rather than requiring the user to manually enter the name of the "Execute" command in front of the name of the script file.

FIBB_HOLD

(bit #7) This bit works in conjunction with the FIBB_PURE bit and has the effect of making a shell command resident immediately after it has been loaded for the first time.

FIBB_GRP_DELETE

(bit #8) see below.

FIBB_GRP_EXECUTE

(bit #9) see below.

FIBB_GRP_WRITE

(bit #10) see below.

FIBB_GRP_READ

(bit #11) see below.

FIBB_OTR_DELETE

(bit #12) see below.

FIBB_OTR_EXECUTE

(bit #13) see below.

FIBB_OTR_WRITE

(bit #14) see below.

FIBB_OTR_READ

(bit #15) These bits are used by network file system server software, such as the Commodore "Envoy" peer to peer file system or the NFS server which was part of the Commodore AS225R2 TCP/IP stack. The local Amiga file systems ignore their respective meanings.

The bits serve identical purposes with regard to whether access to a directory entry is permitted (read and write) whether a program may be executed or deleted. If set, the bits governing execute/read/write operations grant access. If clear, they deny access for execute/read/write operations. The respective delete bit protects a directory entry from deletion if it is set.

These four bits are associated with two different applications.

FIBB_GRP_DELETE through FIBB_GRP_READ control whether a user who is a member of the same group as the owner of the directory entry is allowed to access it and what operations may be performed.

FIBB_OTR_DELETE through FIBB_OTR_READ control whether a user who is not a member of the same group as the owner of the directory is allowed to access it and what operations may be performed.

fib_Size (LONG)

This field holds the size of directory entry in bytes. This meaning applies only to files and hard links to files. For any other type of directory entry, you should ignore it altogether.

Due to general limitations in the design and implementation of dos.library file sizes cannot be accurately reported if they exceed 2 GBytes (2,147,483,647 bytes). A file system may support access to files whose sizes far exceed this limitation, but the number of bytes stored, as reported, will be unreliable. As a rule of thumb, negative file sizes should not be trusted because the size given is bound to be ambiguous, if not outright wrong.

fib_NumBlocks (LONG)

The file system may provide a rough figure of how many blocks (a block is the smallest individually accessible unit of the file system storage medium; 512 bytes used to be the industry standard size in the 1980'ies and early 1990'ies) are required to store the data and/or metadata of a directory entry. Some file systems only report the number of blocks used by the data of a file, some include the number of metadata and supporting file system data structure blocks along with this figure. There is no general standard behaviour for a file system with regard to what the number of blocks stands for. A file system will report what makes sense for it, but this is as far as consistency goes. The same file stored on a different file system may be reported as using a completely different number of blocks.

fib_Date (struct DateStamp)

This data describes the time and date when this directory entry was created or last modified.

Note:

The fib_Date time/date information represents local time. It is not associated with a specific reference time zone.

fib_Comment

('C' string with room for 79 characters and '\0') A file system may allow the user to record a note for each directory entry, a feature which has been available for the Amiga ROM file system and ram-handler since the very beginning of the Amiga operating system, i.e. Kickstart 1.0 (V30).

Note:

Not all Amiga file systems support the use of comments.

Early (1985/1986) developer material would specify the size of the comment string as 116 characters. However, the Amiga ROM file system would only fill in up to 80 characters of comment text, including the terminating '\0' character. The 116 characters given would include both the 80 character comment string and padding bytes.

fib_OwnerUID (UWORD)

see next

fib_OwnerGID (UWORD)

These two fields are intended to be used by network file system server software, such as the Commodore "Envoy" peer to peer file system or the NFS server which was part of the Commodore AS225R2 TCP/IP stack. The local Amiga file systems ignore their respective meanings.

Both fields default to zero, which stands for the local user ID (= UID) and the associated local group ID (= GID).

Note:

Not all Amiga file systems support the use of owner and group information. These members are then both set to 0.

fib_Reserved

The reserved bytes at the end of the FileInfoBlock structure are intended for future use and should be ignored in the meantime.

Some file systems depend upon the contents of the FileInfoBlock to find the next directory entry to be retrieved by the following ExNext() call. Do not change the contents of the FileInfoBlock after ExNext() has returned. In particular, do not reuse the same FileInfoBlock for ExamineFH() or Examine() until after you have finished scanning the directory.

The original Workbench 1.x era CLI commands "Copy", "Delete", "Dir", "List", "Protect" and "Search" make use of a much shorter form of the 'struct FileInfoBlock' which only covers the first 228 bytes. The full 'struct FileInfoBlock' as defined in <dos/dos.h> is 260 bytes in size. If you implement a file system which is used by one of these old Workbench 1.x era commands, you must limit yourself to fill in only the parts of the 'struct FileInfoBlock' which are covered by the first 228 bytes. If your file system modifies any data beyond this point, you are likely to corrupt the stack of these commands, causing them to crash.

The emphasis on insuring that the FileInfoBlock pointer must be longword aligned is profound. Do not take this lightly. It is easy to overlook this requirement and then face the consequences of memory corruption and worse.

One way of insuring that the FileInfoBlock pointer you provide is properly aligned is to use AllocDosObject(DOS_FIB, NULL) which is available in V36.

Prior to that, in Kickstart 1.2/1.3 (V33/V34) you may want to fall back onto AllocMem(sizeof(struct FileInfoBlock), MEMF_ANY|MEMF_PUBLIC) to allocate memory for the infoBlock pointer which will be longword aligned. Use FreeMem(infoBlock, sizeof(struct FileInfoBlock)) when you no longer need it.

When you call Examine() on a Lock which you obtained for a soft link rather than a hard link to a file or directory, the soft link will have already been transparently resolved. Hence, Examine() will not report information about the soft link but rather of the target object of the soft link.

The original Amiga ROM file system in Kickstart 1.0-1.3 would fill in the FileInfoBlock.fib_NumBlocks field by visiting and counting all the data blocks of a file. This would both verify that the file was sound and also significantly increase the time needed to scan a directory. This feature/bug did not carry over to the V34 FastFileSystem and is not present in the Amiga ROM file system versions 36 and beyond (Kickstart 2.0).

Lock(), UnLock(), ExNext(), ExamineFH(), <dos/dos.h>, AllocDosObject(), ExAll(), exec.library/AllocMem