1
0

dirread 1.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103
  1. .TH DIRREAD 2
  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. .IR read (2)
  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. .IR stat (2)
  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. .IR stat (2)
  39. for the layout of a
  40. .BR Dir ).
  41. The array is allocated with
  42. .IR malloc (2)
  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. .IR read (2)
  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 (5)
  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 /sys/src/libc/9sys/dirread.c
  87. .SH SEE ALSO
  88. .IR intro (2),
  89. .IR open (2),
  90. .IR read (2)
  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 .