sys/man/5/read

   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.