jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: getc.3,v 1.18 2025/07/25 18:27:57 tedu Exp $
2.\"
3.\" Copyright (c) 1990, 1991, 1993
4.\" The Regents of the University of California. All rights reserved.
5.\"
6.\" This code is derived from software contributed to Berkeley by
7.\" Chris Torek and the American National Standards Committee X3,
8.\" on Information Processing Systems.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in the
17.\" documentation and/or other materials provided with the distribution.
18.\" 3. Neither the name of the University nor the names of its contributors
19.\" may be used to endorse or promote products derived from this software
20.\" without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.Dd $Mdocdate: July 25 2025 $
35.Dt GETC 3
36.Os
37.Sh NAME
38.Nm fgetc ,
39.Nm getc ,
40.Nm getchar ,
41.Nm getc_unlocked ,
42.Nm getchar_unlocked ,
43.Nm getw
44.Nd get next character or word from input stream
45.Sh SYNOPSIS
46.In stdio.h
47.Ft int
48.Fn fgetc "FILE *stream"
49.Ft int
50.Fn getc "FILE *stream"
51.Ft int
52.Fn getchar "void"
53.Ft int
54.Fn getc_unlocked "FILE *stream"
55.Ft int
56.Fn getchar_unlocked "void"
57.Ft int
58.Fn getw "FILE *stream"
59.Sh DESCRIPTION
60The
61.Fn fgetc
62function obtains the next input character (if present) from the stream
63pointed at by
64.Fa stream ,
65or the next character pushed back on the stream via
66.Xr ungetc 3 .
67.Pp
68The
69.Fn getc
70function acts essentially identically to
71.Fn fgetc ,
72but is a macro that expands in-line.
73.Pp
74The
75.Fn getchar
76function is equivalent to
77.Fn getc
78with the argument
79.Em stdin .
80.Pp
81The
82.Fn getc_unlocked
83and
84.Fn getchar_unlocked
85functions perform the same action, but do not obtain the stream lock.
86They require that the stream first be locked with
87.Xr flockfile 3
88for thread safe operation.
89.Pp
90The
91.Fn getw
92function obtains the next
93.Vt int
94(if present)
95from the stream pointed at by
96.Fa stream .
97.Sh RETURN VALUES
98If successful, these routines return the next requested object from the
99.Fa stream .
100If the stream is at end-of-file or a read error occurs, the routines return
101.Dv EOF .
102The routines
103.Xr feof 3
104and
105.Xr ferror 3
106must be used to distinguish between end-of-file and error.
107If an error occurs, the global variable
108.Va errno
109is set to indicate the error.
110The end-of-file condition is remembered, even on a terminal, and all
111subsequent attempts to read will return
112.Dv EOF
113until the condition is cleared with
114.Xr clearerr 3 .
115.Sh SEE ALSO
116.Xr ferror 3 ,
117.Xr flockfile 3 ,
118.Xr fopen 3 ,
119.Xr fread 3 ,
120.Xr getwc 3 ,
121.Xr putc 3 ,
122.Xr ungetc 3
123.Sh STANDARDS
124The
125.Fn fgetc ,
126.Fn getc ,
127and
128.Fn getchar
129functions conform to
130.St -ansiC .
131The
132.Fn getc_unlocked
133and
134.Fn getchar_unlocked
135functions conform to
136.St -p1003.1-2024 .
137.Sh HISTORY
138The
139.Fn getc
140and
141.Fn getw
142functions first appeared in
143.At v1 ;
144.Fn getchar
145in
146.At v2 ;
147and
148.Fn fgetc
149in
150.At v7 .
151The
152.Fn getc_unlocked
153and
154.Fn getchar_unlocked
155functions have been available since
156.Ox 2.5 .
157.Sh BUGS
158Since
159.Dv EOF
160is a valid integer value,
161.Xr feof 3
162and
163.Xr ferror 3
164must be used to check for failure after calling
165.Fn getw .
166.Pp
167Since the size and byte order of an
168.Vt int
169may vary from one machine to another,
170.Fn getw
171is not recommended for portable applications.