fgetc 3.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213
  1. .TH FGETC 2
  2. .SH NAME
  3. fgetc, getc, getchar, fputc, putc, putchar, ungetc, fgets, gets, fputs, puts, fread, fwrite \- Stdio input and output
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <stdio.h>
  8. .ta \w'\fLlong 'u
  9. .PP
  10. .B
  11. int fgetc(FILE *f)
  12. .PP
  13. .B
  14. int getc(FILE *f)
  15. .PP
  16. .B
  17. int getchar(void)
  18. .PP
  19. .B
  20. int fputc(int c, FILE *f)
  21. .PP
  22. .B
  23. int putc(int c, FILE *f)
  24. .PP
  25. .B
  26. int putchar(int c)
  27. .PP
  28. .B
  29. int ungetc(int c, FILE *f)
  30. .PP
  31. .B
  32. char *fgets(char *s, int n, FILE *f)
  33. .PP
  34. .B
  35. char *gets(char *s)
  36. .PP
  37. .B
  38. int fputs(char *s, FILE *f)
  39. .PP
  40. .B
  41. int puts(char *s)
  42. .PP
  43. .B
  44. long fread(void *ptr, long itemsize, long nitems, FILE *stream)
  45. .PP
  46. .B
  47. long fwrite(void *ptr, long itemsize, long nitems, FILE *stream)
  48. .SH DESCRIPTION
  49. The functions described here work on open Stdio streams (see
  50. .IR fopen ).
  51. .PP
  52. .I Fgetc
  53. returns as an
  54. .B int
  55. the next
  56. .B unsigned
  57. .B char
  58. from input stream
  59. .IR f .
  60. If the stream is at end-of-file, the end-of-file indicator for the
  61. stream is set and
  62. .I fgetc
  63. returns
  64. .BR EOF .
  65. If a read error occurs, the error indicator for the stream is set and
  66. .I fgetc
  67. returns
  68. .BR EOF .
  69. .I Getc
  70. is like
  71. .I fgetc
  72. except that it is implemented as a macro.
  73. .I Getchar
  74. is like
  75. .I getc
  76. except that it always reads from
  77. .BR stdin .
  78. .PP
  79. .I Ungetc
  80. pushes character
  81. .I c
  82. back onto the input stream
  83. .BR f .
  84. The pushed-back character will be returned by subsequent reads in
  85. the reverse order of their pushing.
  86. A successful intervening
  87. .IR fseek ,
  88. .IR fsetpos ,
  89. or
  90. .I rewind
  91. on
  92. .I f
  93. discards any pushed-back characters for
  94. .IR f .
  95. One character of push-back is guaranteed.
  96. .I Ungetc
  97. returns the character pushed back (converted to
  98. .B unsigned
  99. .BR char ),
  100. or
  101. .B EOF
  102. if the operation fails.
  103. A successful call to
  104. .I ungetc
  105. clears the end-of-file indicator for the stream.
  106. The file position indicator for the stream after reading or discarding
  107. all pushed-back characters is the same as it was before the
  108. characters were pushed back.
  109. .PP
  110. .I Fputc
  111. writes character
  112. .I c
  113. (converted to
  114. .B unsigned
  115. .BR char )
  116. to output stream
  117. .IR f
  118. at the position indicated by the position indicator for the stream
  119. and advances the indicator appropriately.
  120. If the file cannot support positioning requests, or if the stream was
  121. opened with append mode, the character is appended to the output stream.
  122. .I Fputc
  123. returns the character written or
  124. .B EOF
  125. if there was a write error.
  126. .I Putc
  127. is like
  128. .IR fputc
  129. but is implemented as a macro.
  130. .I Putchar
  131. is like
  132. .I putc
  133. except that it always writes to
  134. .BR stdout .
  135. .PP
  136. All other input takes place as if characters were read by successive
  137. calls to
  138. .I fgetc
  139. and all other output takes place as if characters were written by
  140. successive calls to
  141. .IR fputc .
  142. .PP
  143. .I Fgets
  144. reads up to and including the next newline, but not past end-of-file
  145. or more than
  146. .IR n -1
  147. characters, from stream
  148. .I f
  149. into array
  150. .IR s .
  151. A null character is written immediately after the last character read
  152. into the array (if any characters are read at all).
  153. .I Fgets
  154. returns
  155. .I s
  156. if successful, otherwise a null pointer.
  157. .I Gets
  158. is similar to
  159. .IR fgets
  160. except that it always reads from
  161. .B stdin
  162. and it discards the terminating newline, if any.
  163. .I Gets
  164. does not check for overflow of the receiving array, so its use is deprecated.
  165. .PP
  166. .I Fputs
  167. writes the string
  168. .I s
  169. to stream
  170. .IR f ,
  171. returning
  172. .B EOF
  173. if a write error occurred, otherwise a nonnegative value.
  174. The terminating null character is not written.
  175. .I Puts
  176. is the same, writing to
  177. .BR stdout .
  178. .PP
  179. .I Fread
  180. reads from the named input
  181. .IR stream
  182. at most
  183. .I nitems
  184. of data of size
  185. .I itemsize
  186. and the type of
  187. .I *ptr
  188. into a block beginning at
  189. .IR ptr .
  190. It returns the number of items actually read.
  191. .PP
  192. .I Fwrite
  193. appends to the named output
  194. .I stream
  195. at most
  196. .I nitems
  197. of data of size
  198. .I itemsize
  199. and the type of
  200. .I *ptr
  201. from a block beginning at
  202. .IR ptr .
  203. It returns the number of items actually written.
  204. .SH SOURCE
  205. .B /sys/src/libstdio
  206. .SH "SEE ALSO"
  207. .IR read (2),
  208. .IR fopen (2),
  209. .IR bio (2)
  210. .SH BUGS
  211. Stdio does not handle
  212. .SM UTF
  213. or runes; use Bio instead.