newlib/libc/stdio/fgetc.c

   1 /*
   2  * Copyright (c) 1990 The Regents of the University of California.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms are permitted
   6  * provided that the above copyright notice and this paragraph are
   7  * duplicated in all such forms and that any documentation,
   8  * and/or other materials related to such
   9  * distribution and use acknowledge that the software was developed
  10  * by the University of California, Berkeley.  The name of the
  11  * University may not be used to endorse or promote products derived
  12  * from this software without specific prior written permission.
  13  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  14  * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  15  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  16  */
  17
  18 /*
  19 FUNCTION
  20 <<fgetc>>, <<fgetc_unlocked>>---get a character from a file or stream
  21
  22 INDEX
  23         fgetc
  24 INDEX
  25         fgetc_unlocked
  26 INDEX
  27         _fgetc_r
  28 INDEX
  29         _fgetc_unlocked_r
  30
  31 SYNOPSIS
  32         #include <stdio.h>
  33         int fgetc(FILE *<[fp]>);
  34
  35         #define _BSD_SOURCE
  36         #include <stdio.h>
  37         int fgetc_unlocked(FILE *<[fp]>);
  38
  39         #include <stdio.h>
  40         int _fgetc_r(struct _reent *<[ptr]>, FILE *<[fp]>);
  41
  42         #define _BSD_SOURCE
  43         #include <stdio.h>
  44         int _fgetc_unlocked_r(struct _reent *<[ptr]>, FILE *<[fp]>);
  45
  46 DESCRIPTION
  47 Use <<fgetc>> to get the next single character from the file or stream
  48 identified by <[fp]>.  As a side effect, <<fgetc>> advances the file's
  49 current position indicator.
  50
  51 For a macro version of this function, see <<getc>>.
  52
  53 <<fgetc_unlocked>> is a non-thread-safe version of <<fgetc>>.
  54 <<fgetc_unlocked>> may only safely be used within a scope
  55 protected by flockfile() (or ftrylockfile()) and funlockfile().  This
  56 function may safely be used in a multi-threaded program if and only
  57 if they are called while the invoking thread owns the (FILE *)
  58 object, as is the case after a successful call to the flockfile() or
  59 ftrylockfile() functions.  If threads are disabled, then
  60 <<fgetc_unlocked>> is equivalent to <<fgetc>>.
  61
  62 The functions <<_fgetc_r>> and <<_fgetc_unlocked_r>> are simply reentrant
  63 versions that are passed the additional reentrant structure pointer
  64 argument: <[ptr]>.
  65
  66 RETURNS
  67 The next character (read as an <<unsigned char>>, and cast to
  68 <<int>>), unless there is no more data, or the host system reports a
  69 read error; in either of these situations, <<fgetc>> returns <<EOF>>.
  70
  71 You can distinguish the two situations that cause an <<EOF>> result by
  72 using the <<ferror>> and <<feof>> functions.
  73
  74 PORTABILITY
  75 ANSI C requires <<fgetc>>.
  76
  77 <<fgetc_unlocked>> is a BSD extension also provided by GNU libc.
  78
  79 Supporting OS subroutines required: <<close>>, <<fstat>>, <<isatty>>,
  80 <<lseek>>, <<read>>, <<sbrk>>, <<write>>.
  81 */
  82
  83 #include <_ansi.h>
  84 #include <stdio.h>
  85 #include "local.h"
  86
  87 int
  88 _fgetc_r (struct _reent * ptr,
  89        FILE * fp)
  90 {
  91   int result;
  92   CHECK_INIT(ptr, fp);
  93   _newlib_flockfile_start (fp);
  94   result = __sgetc_r (ptr, fp);
  95   _newlib_flockfile_end (fp);
  96   return result;
  97 }
  98
  99 #ifndef _REENT_ONLY
 100
 101 int
 102 fgetc (FILE * fp)
 103 {
 104 #if !defined(PREFER_SIZE_OVER_SPEED) && !defined(__OPTIMIZE_SIZE__)
 105   int result;
 106   struct _reent *reent = _REENT;
 107
 108   CHECK_INIT(reent, fp);
 109   _newlib_flockfile_start (fp);
 110   result = __sgetc_r (reent, fp);
 111   _newlib_flockfile_end (fp);
 112   return result;
 113 #else
 114   return _fgetc_r (_REENT, fp);
 115 #endif
 116 }
 117
 118 #endif /* !_REENT_ONLY */
 119