sys/man/2/fgetc

   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.