NAME
        ExNext -- examine the next entry in a directory

    SYNOPSIS
        success = ExNext( lock, fileinfoblock )
        D0                 D1        D2

        bool exnext(bptr, struct fileinfoblock *)

    FUNCTION
        This routine is passed a directory lock and a fileinfoblock that
        have been initialized by a previous call to examine(), or updated
        by a previous call to ExNext().  ExNext() gives a return code of zero
        on failure.  The most common cause of failure is reaching the end
        of the list of files in the owning directory.  In this case, ioerr
        will return ERROR_NO_MORE_ENTRIES and a good exit is appropriate.

        So, follow these steps to examine a directory:
        1) Pass a lock and a fileinfoblock to examine().  the lock must
           be on the directory you wish to examine.
        2) Pass ExNext() the same lock and fileinfoblock.
        3) Do something with the information returned in the fileinfoblock.
           Note that the fib_DirEntryType field is positive for directories,
           negative for files.
        4) Keep calling ExNext() until it returns FALSE.  Check ioerr()
           to ensure that the reason for failure was ERROR_NO_MORE_ENTRIES.

        Note: if you wish to recursively scan the file tree and you find
        another directory while ExNext()ing you must lock that directory and
        examine() it using a new fileinfoblock.  use of the same
        fileinfoblock to enter a directory would lose important state
        information such that it will be impossible to continue scanning
        the parent directory.  While it is permissible to unlock() and lock()
        the parent directory between ExNext() calls, this is NOT recommended.
        Important state information is associated with the parent lock, so
        if it is freed between ExNext() calls this information has to be
        rebuilt on each new ExNext() call, and will significantly slow down
        directory scanning.

        It is NOT legal to examine() a file, and then to exnext() from that
        fileinfoblock.     you may make a local copy of the fileinfoblock, as
        long as it is never passed back to the operating system.

    INPUTS
        lock - BCPL pointer to a lock originally used for the examine() call
        infoBlock - pointer to a fileinfoblock used on the previous examine()
                    or ExNext() call.

    RESULTS
        success - boolean

    SPECIAL NOTE
        fileinfoblock must be longword-aligned.  allocdosobject() will
        allocate them correctly for you.

    SEE ALSO
        examine(), lock(), unlock(), ioerr(), examinefh(), allocdosobject(),
        exall()