1fgetc(3C)                Standard C Library Functions                fgetc(3C)
2
3
4

NAME

6       fgetc,  getc,  getc_unlocked,  getchar,  getchar_unlocked, getw - get a
7       byte from a stream
8

SYNOPSIS

10       #include <stdio.h>
11
12       int fgetc(FILE *stream);
13
14
15       int getc(FILE *stream);
16
17
18       int getc_unlocked(FILE *stream);
19
20
21       int getchar(void);
22
23
24       int getchar_unlocked(void);
25
26
27       int getw(FILE *stream);
28
29

DESCRIPTION

31       The fgetc() function obtains the next byte (if present) as an  unsigned
32       char  converted  to an int, from the input stream pointed to by stream,
33       and advances the associated file position indicator for the stream  (if
34       defined).
35
36
37       For standard-conforming (see standards(5)) applications, if the end-of-
38       file indicator for the stream is set, fgetc() returns  EOF  whether  or
39       not a next byte is present.
40
41
42       The fgetc() function may mark the st_atime field of the file associated
43       with stream for update. The st_atime field will be marked for update by
44       the  first  successful  execution  of  fgetc(),  fgets(3C),  fread(3C),
45       fscanf(3C), getc(), getchar(), gets(3C) or scanf(3C) using stream  that
46       returns data not supplied by a prior call to ungetc(3C) or ungetwc(3C).
47
48
49       The  getc()  function is functionally identical to fgetc(), except that
50       it is implemented as a macro. It runs faster than fgetc(), but it takes
51       up  more space per invocation and its name cannot be passed as an argu‐
52       ment to a function call.
53
54
55       The getchar() routine is equivalent to getc(stdin). It  is  implemented
56       as a macro.
57
58
59       The  getc_unlocked()  and  getchar_unlocked()  routines are variants of
60       getc() and getchar(), respectively, that do not lock the stream.  It is
61       the  caller's  responsibility to acquire the stream lock before calling
62       these routines and releasing the lock afterwards; see flockfile(3C) and
63       stdio(3C). These routines are implemented as macros.
64
65
66       The  getw() function reads the next word from the stream. The size of a
67       word is the size of an int and may vary from  environment  to  environ‐
68       ment.  The getw() function presumes no special alignment in the file.
69
70
71       The  getw() function may mark the st_atime field of the file associated
72       with stream for update. The st_atime field will be marked for update by
73       the  first  successful  execution  of  fgetc(),  fgets(3C),  fread(3C),
74       getc(), getchar(), gets(3C), fscanf(3C) or scanf(3C) using stream  that
75       returns data not supplied by a prior call to ungetc(3C).
76

RETURN VALUES

78       Upon   successful   completion,   fgetc(),   getc(),   getc_unlocked(),
79       getchar(), getchar_unlocked(), and getw() return the next byte from the
80       input stream pointed to by stream. If the stream is at end-of-file, the
81       end-of-file indicator for the stream is set and these functions  return
82       EOF.  For  standard-conforming  (see standards(5)) applications, if the
83       end-of-file indicator for the stream is set, these functions return EOF
84       whether  or  not  the stream is at end-of-file. If a read error occurs,
85       the error indicator for the stream is set, EOF is returned,  and  errno
86       is set to indicate the error.
87

ERRORS

89       The  fgetc(),  getc(),  getc_unlocked(), getchar(), getchar_unlocked(),
90       and getw() functions will fail if data needs to be read and:
91
92       EAGAIN       The O_NONBLOCK flag is set for the file descriptor  under‐
93                    lying  stream  and  the  process  would  be delayed in the
94                    fgetc() operation.
95
96
97       EBADF        The file descriptor underlying stream is not a valid  file
98                    descriptor open for reading.
99
100
101       EINTR        The  read operation was terminated due to the receipt of a
102                    signal, and no data was transferred.
103
104
105       EIO          A physical I/O error has occurred, or the process is in  a
106                    background  process group attempting to read from its con‐
107                    trolling terminal, and either the process is  ignoring  or
108                    blocking  the  SIGTTIN  signal  or  the  process  group is
109                    orphaned. This error may also be generated for implementa‐
110                    tion-dependent reasons.
111
112
113       EOVERFLOW    The file is a regular file and an attempt was made to read
114                    at or beyond the offset maximum associated with the corre‐
115                    sponding stream.
116
117
118
119       The  fgetc(),  getc(),  getc_unlocked(), getchar(), getchar_unlocked(),
120       and getw() functions may fail if:
121
122       ENOMEM    Insufficient storage space is available.
123
124
125       ENXIO     A request was made of a non-existent device, or  the  request
126                 was outside the capabilities of the device.
127
128

USAGE

130       If  the  integer  value  returned  by fgetc(), getc(), getc_unlocked(),
131       getchar(), getchar_unlocked(), and getw() is stored into a variable  of
132       type  char and then compared against the integer constant EOF, the com‐
133       parison may never succeed, because sign-extension of a variable of type
134       char on widening to integer is implementation-dependent.
135
136
137       The  ferror(3C)  or  feof(3C)  functions  must  be  used to distinguish
138       between an error condition and an end-of-file condition.
139
140
141       Functions  exist  for  the  getc(),  getc_unlocked(),  getchar(),   and
142       getchar_unlocked()  macros.  To  get  the function form, the macro name
143       must be undefined (for example, #undef getc).
144
145
146       When the macro forms are used, getc() and getc_unlocked() evaluate  the
147       stream  argument  more  than  once. In particular, getc(*f++); does not
148       work sensibly.  The fgetc() function should be used instead when evalu‐
149       ating the stream argument has side effects.
150
151
152       Because of possible differences in word length and byte ordering, files
153       written using getw() are machine-dependent, and may not be  read  using
154       getw() on a different processor.
155
156
157       The  getw() function is inherently byte stream-oriented and is not ten‐
158       able in the context of either multibyte character streams or wide-char‐
159       acter  streams.  Application  programmers are recommended to use one of
160       the character-based input functions instead.
161

ATTRIBUTES

163       See attributes(5) for descriptions of the following attributes:
164
165
166
167
168       ┌─────────────────────────────┬─────────────────────────────┐
169       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
170       ├─────────────────────────────┼─────────────────────────────┤
171       │Interface Stability          │fgetc(),            getc(),  │
172       │                             │getc_unlocked(), getchar(),  │
173       │                             │and getchar_unlocked()  are  │
174       │                             │Standard.                    │
175       ├─────────────────────────────┼─────────────────────────────┤
176       │MT-Level                     │See NOTES below.             │
177       └─────────────────────────────┴─────────────────────────────┘
178

SEE ALSO

180       Intro(3),    __fsetlocking(3C),    fclose(3C),   feof(3C),   fgets(3C),
181       fgetwc(3C),   fgetws(3C),    flockfile(3C),    fopen(3C),    fread(3C),
182       fscanf(3C),   gets(3C),  putc(3C),  scanf(3C),  stdio(3C),  ungetc(3C),
183       ungetwc(3C), attributes(5), standards(5)
184

NOTES

186       The fgetc(), getc(), getchar(), and getw() routines are MT-Safe in mul‐
187       tithreaded  applications.   The  getc_unlocked() and getchar_unlocked()
188       routines are unsafe in multithreaded applications.
189
190
191
192SunOS 5.11                        15 Oct 2003                        fgetc(3C)
Impressum