Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
fgetc(3C)		 Standard C Library Functions		     fgetc(3C)

NAME
       fgetc,  getc,  getc_unlocked,  getchar,	getchar_unlocked, getw - get a
       byte from a stream

SYNOPSIS
       #include	<stdio.h>

       int fgetc(FILE *stream);

       int getc(FILE *stream);

       int getc_unlocked(FILE *stream);

       int getchar(void);

       int getchar_unlocked(void);

       int getw(FILE *stream);

DESCRIPTION
       The fgetc() function obtains the	next byte (if present) as an  unsigned
       char  converted	to an int, from	the input stream pointed to by stream,
       and advances the	associated file	position indicator for the stream  (if
       defined).

       For standard-conforming (see standards(5)) applications,	if the end-of-
       file indicator for the stream is	set, fgetc() returns  EOF  whether  or
       not a next byte is present.

       The fgetc() function may	mark the st_atime field	of the file associated
       with stream for update. The st_atime field will be marked for update by
       the  first  successful  execution of fgetc(), fgets(3C),	fread(3C), fs-
       canf(3C), getc(), getchar(), gets(3C) or	scanf(3C)  using  stream  that
       returns data not	supplied by a prior call to ungetc(3C) or ungetwc(3C).

       The  getc()  function is	functionally identical to fgetc(), except that
       it is implemented as a macro. It	runs faster than fgetc(), but it takes
       up  more	space per invocation and its name cannot be passed as an argu-
       ment to a function call.

       The getchar() routine is	equivalent to getc(stdin). It  is  implemented
       as a macro.

       The  getc_unlocked()  and  getchar_unlocked()  routines are variants of
       getc() and getchar(), respectively, that	do not lock the	stream.	 It is
       the  caller's  responsibility to	acquire	the stream lock	before calling
       these routines and releasing the	lock afterwards; see flockfile(3C) and
       stdio(3C). These	routines are implemented as macros.

       The  getw() function reads the next word	from the stream. The size of a
       word is the size	of an int and may vary from  environment  to  environ-
       ment.  The getw() function presumes no special alignment	in the file.

       The  getw() function may	mark the st_atime field	of the file associated
       with stream for update. The st_atime field will be marked for update by
       the  first  successful  execution  of  fgetc(),	fgets(3C),  fread(3C),
       getc(), getchar(), gets(3C), fscanf(3C) or scanf(3C) using stream  that
       returns data not	supplied by a prior call to ungetc(3C).

RETURN VALUES
       Upon   successful   completion,	 fgetc(),   getc(),   getc_unlocked(),
       getchar(), getchar_unlocked(), and getw() return	the next byte from the
       input  stream  pointed  to by stream.  If the stream is at end-of-file,
       the end-of-file indicator for the stream	is set and these functions re-
       turn  EOF.  For standard-conforming (see	standards(5)) applications, if
       the end-of-file indicator for the stream	is set,	these functions	return
       EOF  whether  or	 not the stream	is at end-of-file. If a	read error oc-
       curs, the error indicator for the stream	is set,	EOF is	returned,  and
       errno is	set to indicate	the error.

ERRORS
       The  fgetc(),  getc(),  getc_unlocked(),	getchar(), getchar_unlocked(),
       and getw() functions will fail if data needs to be read and:

       EAGAIN	       The O_NONBLOCK flag is set for the file descriptor  un-
		       derlying	stream and the process would be	delayed	in the
		       fgetc() operation.

       EBADF	       The file	descriptor underlying stream is	 not  a	 valid
		       file descriptor open for	reading.

       EINTR	       The read	operation was terminated due to	the receipt of
		       a signal, and no	data was transferred.

       EIO	       A physical I/O error has	occurred, or the process is in
		       a  background process group attempting to read from its
		       controlling terminal, and either	the process is	ignor-
		       ing or blocking the SIGTTIN signal or the process group
		       is orphaned. This error may also	be generated  for  im-
		       plementation-dependent reasons.

       EOVERFLOW       The  file  is a regular file and	an attempt was made to
		       read at or beyond the offset  maximum  associated  with
		       the corresponding stream.

       The  fgetc(),  getc(),  getc_unlocked(),	getchar(), getchar_unlocked(),
       and getw() functions may	fail if:

       ENOMEM	       Insufficient storage space is available.

       ENXIO	       A request was made of a non-existent device, or the re-
		       quest was outside the capabilities of the device.

USAGE
       If  the	integer	 value	returned  by fgetc(), getc(), getc_unlocked(),
       getchar(), getchar_unlocked(), and getw() is stored into	a variable  of
       type  char and then compared against the	integer	constant EOF, the com-
       parison may never succeed, because sign-extension of a variable of type
       char on widening	to integer is implementation-dependent.

       The  ferror(3C)	or  feof(3C) functions must be used to distinguish be-
       tween an	error condition	and an end-of-file condition.

       Functions  exist	 for  the  getc(),  getc_unlocked(),  getchar(),   and
       getchar_unlocked()  macros.  To	get  the function form,	the macro name
       must be undefined (for example, #undef getc).

       When the	macro forms are	used, getc() and getc_unlocked() evaluate  the
       stream  argument	 more  than  once. In particular, getc(*f++); does not
       work sensibly.  The fgetc() function should be used instead when	evalu-
       ating the stream	argument has side effects.

       Because of possible differences in word length and byte ordering, files
       written using getw() are	machine-dependent, and may not be  read	 using
       getw() on a different processor.

       The  getw() function is inherently byte stream-oriented and is not ten-
       able in the context of either multibyte character streams or wide-char-
       acter  streams.	Application  programmers are recommended to use	one of
       the character-based input functions instead.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |fgetc(),	getc(),	 getc_un-  |
       |			     |locked(),	  getchar(),  and  |
       |			     |getchar_unlocked()      are  |
       |			     |Standard.			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |See NOTES	below.		   |
       +-----------------------------+-----------------------------+

SEE ALSO
       intro(3),    __fsetlocking(3C),	  fclose(3C),	feof(3C),   fgets(3C),
       fgetwc(3C),  fgetws(3C),	 flockfile(3C),	 fopen(3C),   fread(3C),   fs-
       canf(3C),   gets(3C),   putc(3C),   scanf(3C),  stdio(3C),  ungetc(3C),
       ungetwc(3C), attributes(5), standards(5)

NOTES
       The fgetc(), getc(), getchar(), and getw() routines are MT-Safe in mul-
       tithreaded  applications.   The	getc_unlocked()	and getchar_unlocked()
       routines	are unsafe in multithreaded applications.

SunOS 5.10			  15 Oct 2003			     fgetc(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fgetc&sektion=3c&manpath=SunOS+5.10>

home | help