tdirread.3 - plan9port - [fork] Plan 9 from user space
  HTML git clone git://src.adamsgaard.dk/plan9port
   DIR Log
   DIR Files
   DIR Refs
   DIR README
   DIR LICENSE
       ---
       tdirread.3 (1898B)
       ---
            1 .TH DIRREAD 3
            2 .SH NAME
            3 dirread, dirreadall \- read directory
            4 .SH SYNOPSIS
            5 .B #include <u.h>
            6 .br
            7 .B #include <libc.h>
            8 .PP
            9 .B
           10 long dirread(int fd, Dir **buf)
           11 .PP
           12 .B
           13 long dirreadall(int fd, Dir **buf)
           14 .PP
           15 .B
           16 #define        STATMAX        65535U
           17 .PP
           18 .B
           19 #define        DIRMAX        (sizeof(Dir)+STATMAX)
           20 .SH DESCRIPTION
           21 The data returned by a
           22 .MR read (3)
           23 on a directory is a set of complete directory entries
           24 in a machine-independent format, exactly equivalent to
           25 the result of a
           26 .MR stat (3)
           27 on each file or subdirectory in the directory.
           28 .I Dirread
           29 decodes the directory entries into a machine-dependent form.
           30 It reads from
           31 .IR fd
           32 and unpacks the data into an array of
           33 .B Dir
           34 structures
           35 whose address is returned in
           36 .B *buf
           37 (see
           38 .MR stat (3)
           39 for the layout of a
           40 .BR Dir ).
           41 The array is allocated with
           42 .MR malloc (3)
           43 each time
           44 .I dirread
           45 is called.
           46 .PP
           47 .I Dirreadall
           48 is like
           49 .IR dirread ,
           50 but reads in the entire directory; by contrast,
           51 .I dirread
           52 steps through a directory one
           53 .MR read (3)
           54 at a time.
           55 .PP
           56 Directory entries have variable length.
           57 A successful
           58 .I read
           59 of a directory always returns an integral number of complete directory entries;
           60 .I dirread
           61 always returns complete
           62 .B Dir
           63 structures.
           64 See
           65 .IR read (9p)
           66 for more information.
           67 .PP
           68 The constant
           69 .B STATMAX
           70 is the maximum size that a directory entry can occupy.
           71 The constant
           72 .B DIRMAX
           73 is an upper limit on the size necessary to hold a
           74 .B Dir
           75 structure and all the associated data.
           76 .PP
           77 .I Dirread
           78 and
           79 .I dirreadall
           80 return the number of
           81 .B Dir
           82 structures filled in
           83 .BR buf .
           84 The file offset is advanced by the number of bytes actually read.
           85 .SH SOURCE
           86 .B \*9/src/lib9/dirread.c
           87 .SH SEE ALSO
           88 .MR intro (3) ,
           89 .MR open (3) ,
           90 .MR read (3)
           91 .SH DIAGNOSTICS
           92 .I Dirread
           93 and
           94 .I Dirreadall
           95 return zero for end of file and a negative value for error.
           96 In either case,
           97 .B *buf
           98 is set to
           99 .B nil
          100 so the pointer can always be freed with impunity.
          101 .PP
          102 These functions set
          103 .IR errstr .