read 1.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596
  1. .TH READ 2
  2. .SH NAME
  3. read, readn, write, pread, pwrite \- read or write file
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <libc.h>
  8. .PP
  9. .B
  10. long read(int fd, void *buf, long nbytes)
  11. .PP
  12. .B
  13. long readn(int fd, void *buf, long nbytes)
  14. .PP
  15. .B
  16. long write(int fd, void *buf, long nbytes)
  17. .PP
  18. .B
  19. long pread(int fd, void *buf, long nbytes, vlong offset)
  20. .PP
  21. .B
  22. long pwrite(int fd, void *buf, long nbytes, vlong offset)
  23. .SH DESCRIPTION
  24. .I Read
  25. reads
  26. .I nbytes
  27. bytes of data
  28. from the offset in the file associated with
  29. .I fd
  30. into memory at
  31. .IR buf .
  32. The offset is advanced by the number of bytes read.
  33. It is not guaranteed
  34. that all
  35. .I nbytes
  36. bytes will be read; for example
  37. if the file refers to the console, at most one line
  38. will be returned.
  39. In any event the number of bytes read is returned.
  40. A return value of
  41. 0 is conventionally interpreted as end of file.
  42. .PP
  43. .I Readn
  44. is just like read, but does successive
  45. .I read
  46. calls until
  47. .I nbytes
  48. have been read, or a read system call
  49. returns a non-positive count.
  50. .PP
  51. .I Write
  52. writes
  53. .I nbytes
  54. bytes of data starting at
  55. .I buf
  56. to the file associated with
  57. .I fd
  58. at the file offset.
  59. The offset is advanced by the number of bytes written.
  60. The number of characters actually written is returned.
  61. It should be regarded as an error
  62. if this is not the same as requested.
  63. .PP
  64. .I Pread
  65. and
  66. .I Pwrite
  67. are equivalent to a
  68. .IR seek (2)
  69. to
  70. .I offset
  71. followed by a
  72. .I read
  73. or
  74. .IR write .
  75. By combining the operations in a single atomic call, they more closely
  76. match the 9P protocol
  77. (see
  78. .IR intro (5))
  79. and, more important,
  80. permit multiprocess programs to execute multiple concurrent
  81. read and write operations on the same file descriptor
  82. without interference.
  83. .SH SOURCE
  84. .B /sys/src/libc/9syscall
  85. .br
  86. .B /sys/src/libc/port/readn.c
  87. .SH SEE ALSO
  88. .IR intro (2),
  89. .IR dirread (2),
  90. .IR dup (2),
  91. .IR open (2),
  92. .IR pipe (2),
  93. .IR readv (2)
  94. .SH DIAGNOSTICS
  95. These functions set
  96. .IR errstr .