GETC man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

FGETC(3C)							     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),
       fscanf(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	return
       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 occurs,
       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	under‐
		    lying  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 con‐
		    trolling terminal, and either the process is  ignoring  or
		    blocking  the  SIGTTIN  signal  or	the  process  group is
		    orphaned. This error may also be generated for implementa‐
		    tion-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 corre‐
		    sponding 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  request
		 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
       between 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_unlocked(),		 │
       │		    │ 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),
       fscanf(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.

				 Oct 15, 2003			     FGETC(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net