read 2.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125
  1. .TH READ 5
  2. .SH NAME
  3. read, write \- transfer data from and to a file
  4. .SH SYNOPSIS
  5. .ta \w'\fLTwrite 'u
  6. .IR size [4]
  7. .B Tread
  8. .IR tag [2]
  9. .IR fid [4]
  10. .IR offset [8]
  11. .IR count [4]
  12. .br
  13. .IR size [4]
  14. .B Rread
  15. .IR tag [2]
  16. .IR count [4]
  17. .IR data [ count ]
  18. .PP
  19. .IR size [4]
  20. .B Twrite
  21. .IR tag [2]
  22. .IR fid [4]
  23. .IR offset [8]
  24. .IR count [4]
  25. .IR data [ count ]
  26. .br
  27. .IR size [4]
  28. .B Rwrite
  29. .IR tag [2]
  30. .IR count [4]
  31. .SH DESCRIPTION
  32. The
  33. .B read
  34. request
  35. asks for
  36. .I count
  37. bytes of data
  38. from the file identified by
  39. .IR fid ,
  40. which must be opened for reading,
  41. starting
  42. .I offset
  43. bytes after the beginning of the file.
  44. The bytes are returned with the
  45. .B read
  46. reply message.
  47. .PP
  48. The
  49. .I count
  50. field in the reply indicates the number of bytes returned.
  51. This may be less than the requested amount.
  52. If the
  53. .I offset
  54. field is greater than or equal to the number of bytes in the file,
  55. a count of zero will be returned.
  56. .PP
  57. For directories,
  58. .B read
  59. returns an integral number of
  60. directory entries exactly as in
  61. .B stat
  62. (see
  63. .IR stat (5)),
  64. one for each member of the directory.
  65. The
  66. .B read
  67. request message must have
  68. .B offset
  69. equal to zero or the value of
  70. .B offset
  71. in the previous
  72. .B read
  73. on the directory, plus the number of bytes
  74. returned in the previous
  75. .BR read .
  76. In other words, seeking other than to the beginning
  77. is illegal in a directory (see
  78. .IR seek (2)).
  79. .PP
  80. The
  81. .B write
  82. request asks that
  83. .I count
  84. bytes of data be recorded in the file identified by
  85. .IR fid ,
  86. which must be opened for writing, starting
  87. .I offset
  88. bytes after the beginning of the file.
  89. If the file is append-only,
  90. the data will be placed at the end of the file regardless of
  91. .IR offset .
  92. Directories may not be written.
  93. .PP
  94. The
  95. .B write
  96. reply records the number of bytes actually written.
  97. It is usually an error
  98. if this is not the same as requested.
  99. .PP
  100. Because 9P implementations may limit the size of individual
  101. messages,
  102. more than one message may be produced by a single
  103. .I read
  104. or
  105. .I write
  106. call.
  107. The
  108. .I iounit
  109. field returned by
  110. .IR open (5),
  111. if non-zero, reports the maximum size that is guaranteed
  112. to be transferred atomically.
  113. .SH ENTRY POINTS
  114. .B Read
  115. and
  116. .B write
  117. messages are generated by the corresponding calls.
  118. Because they include an offset, the
  119. .I pread
  120. and
  121. .I pwrite
  122. calls correspond more directly to the 9P messages.
  123. Although
  124. .IR seek (2)
  125. affects the offset, it does not generate a message.