Museum

NAME_$READ_DIR_LC                 Domain/OS                  NAME_$READ_DIR_LC


NAME
     name_$read_dir_lc - read a directory

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/name.h>

     void name_$read_dir_lc(
          char *dir_name,
          unsigned short &name_length,
          boolean *seek_to_bof,
          name_$cursor_t *index,
          unsigned short &max_count,
          unsigned long &dir_data_size,
          char *dir_data,
          unsigned short *read_count,
          status_$t *status)

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/name.ins.pas';

     procedure name_$read_dir_lc(
          in dir_name: univ name_$long_pname_t;
          in name_length: integer;
          var seek_to_bof: boolean;
          var index: name_$cursor_t;
          in max_count: pinteger;
          in dir_data_size: linteger;
          out dir_data: univ name_$buf_t;
          out read_count: pinteger;
          out status: status_$t);

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/name.ins.ftn'

           integer*4 dir_data_size
           parameter dir_data_size = 1024

           character dir_name*1023, index*300, dir_data*(dir_data_size)
           integer*2 name_length, max_count, read_count
           logical seek_to_bof
           integer*4 status

           character canonical_entry*278, entname*255
           integer*2 entnxt, enttype, entlen

           equivalence (entnxt, canonical_entry(1: 2))
           equivalence (enttype, canonical_entry(3: 4))
           equivalence (entlen, canonical_entry(21: 22))
           equivalence (entname, canonical_entry(23: 278))

           call name_$read_dir(dir_name, name_length, seek_to_bof,
          &                    index, max_count, dir_data_size,
          &                    dir_data, read_count, status)

DESCRIPTION
     Name_$read_dir_lc supplies a list of up to max_count canonical directory
     entries.  It will return fewer entries than requested if the requested
     number of directory entries exceeds the amount of space available in
     dir_data.

     To extract information from dir_data,  programmers should treat it as a
     pointer to an object of type name_$canonical_dir_entry_t.  The entnxt
     field gives the offset within dir_data of the next record, if more than
     one record was requested.

     dir_name
          The pathname of the directory to read.

     name_length
          The number of bytes in dir_name.

     seek_to_bof
          A Boolean that determines where name_$read_dir_lc will start reading
          the directory.  If seek_to_bof is true, name_$read_dir_lc starts at
          the beginning of the directory and supplies the first entry of the
          directory in dir_data.  Otherwise, name_$read_dir_lc supplies the
          next unread directory entry as indicated by index.

          To read an entire directory, set seek_to_bof to true on the first
          call to name_$read_dir_lc and leave it alone for succeeding calls on
          the directory; name_$read_dir_lc always sets seek_to_bof to false
          before returning.

     index
          An argument used by name_$read_dir_lc to maintain its place in the
          directory.  Name_$read_dir_lc initializes and maintains index;
          altering index between successive reads from a directory will con-
          fuse the directory entry sequence returned in dir_data.

     max_count
          The maximum number of directory entries to read from dir_name.

     dir_data_size
          The number of bytes available in dir_data.  Name_$read_dir_lc will
          not write more than dir_data_size bytes into dir_data.

     dir_data
          A buffer for the canonical directory entries supplied by
          name_$read_dir_lc.

     read_count
          The number of directory entries actually supplied in dir_data.  If
          there are fewer than max_count unread entries left in dir_name, then
          read_count will be less than max_count.  If there are no unread
          entries left in dir_name when name_$read_dir_lc is called, then it
          will return with a read_count of 0.

     status
          The completion status.

NOTES
     FORTRAN programmers may wish to call name_$extract_data_lc to interpret
     the data returned by name_$read_dir_lc.  Programs that call
     name_$extract_read_data_lc should set the max_count argument to 1 when
     calling name_$read_dir_lc.