original/man3/fgetc.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu)
  26 .\" Modified Fri Sep  8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl)
  27 .TH FGETC 3  2013-12-31 "GNU" "Linux Programmer's Manual"
  28 .SH NAME
  29 fgetc, fgets, getc, getchar, ungetc \- input of characters and strings
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <stdio.h>
  33 .sp
  34 .BI "int fgetc(FILE *" stream );
  35
  36 .BI "char *fgets(char *" "s" ", int " "size" ", FILE *" "stream" );
  37
  38 .BI "int getc(FILE *" stream );
  39
  40 .B "int getchar(void);"
  41
  42 .BI "int ungetc(int " c ", FILE *" stream );
  43 .fi
  44 .SH DESCRIPTION
  45 .BR fgetc ()
  46 reads the next character from
  47 .I stream
  48 and returns it as an
  49 .I unsigned char
  50 cast to an
  51 .IR int ,
  52 or
  53 .B EOF
  54 on end of file or error.
  55 .PP
  56 .BR getc ()
  57 is equivalent to
  58 .BR fgetc ()
  59 except that it may be implemented as a macro which evaluates
  60 .I stream
  61 more than once.
  62 .PP
  63 .BR getchar ()
  64 is equivalent to
  65 .BI "getc(" stdin ) \fR.
  66 .PP
  67 .BR fgets ()
  68 reads in at most one less than
  69 .I size
  70 characters from
  71 .I stream
  72 and stores them into the buffer pointed to by
  73 .IR s .
  74 Reading stops after an
  75 .B EOF
  76 or a newline.
  77 If a newline is read, it is stored into the buffer.
  78 A terminating null byte (\(aq\e0\(aq)
  79 is stored after the last character in the buffer.
  80 .PP
  81 .BR ungetc ()
  82 pushes
  83 .I c
  84 back to
  85 .IR stream ,
  86 cast to
  87 .IR "unsigned char" ,
  88 where it is available for subsequent read operations.
  89 Pushed-back characters
  90 will be returned in reverse order; only one pushback is guaranteed.
  91 .PP
  92 Calls to the functions described here can be mixed with each other and with
  93 calls to other input functions from the
  94 .I stdio
  95 library for the same input stream.
  96 .PP
  97 For nonlocking counterparts, see
  98 .BR unlocked_stdio (3).
  99 .SH RETURN VALUE
 100 .BR fgetc (),
 101 .BR getc ()
 102 and
 103 .BR getchar ()
 104 return the character read as an
 105 .I unsigned char
 106 cast to an
 107 .I int
 108 or
 109 .B EOF
 110 on end of file or error.
 111 .PP
 112 .BR fgets ()
 113 returns
 114 .I s
 115 on success, and NULL
 116 on error or when end of file occurs while no characters have been read.
 117 .PP
 118 .BR ungetc ()
 119 returns
 120 .I c
 121 on success, or
 122 .B EOF
 123 on error.
 124 .SH CONFORMING TO
 125 C89, C99, POSIX.1-2001.
 126
 127 It is not advisable to mix calls to input functions from the
 128 .I stdio
 129 library with low-level calls to
 130 .BR read (2)
 131 for the file descriptor associated with the input stream; the results
 132 will be undefined and very probably not what you want.
 133 .SH SEE ALSO
 134 .BR read (2),
 135 .BR write (2),
 136 .BR ferror (3),
 137 .BR fgetwc (3),
 138 .BR fgetws (3),
 139 .BR fopen (3),
 140 .BR fread (3),
 141 .BR fseek (3),
 142 .BR getline (3),
 143 .BR gets (3),
 144 .BR getwchar (3),
 145 .BR puts (3),
 146 .BR scanf (3),
 147 .BR ungetwc (3),
 148 .BR unlocked_stdio (3),
 149 .BR feature_test_macros (7)
 150 .SH COLOPHON
 151 This page is part of release 3.79 of the Linux
 152 .I man-pages
 153 project.
 154 A description of the project,
 155 information about reporting bugs,
 156 and the latest version of this page,
 157 can be found at
 158 \%http://www.kernel.org/doc/man\-pages/.