Manual Pages for UNIX Operating System command usage for man putchar_unlocked

Standard C Library Functions                            fputc(3C)



NAME
     fputc, putc, putc_unlocked, putchar, putchar_unlocked,  putw
     - put a byte on a stream

SYNOPSIS
     #include 

     int fputc(int c, FILE *stream);


     int putc(int c, FILE *stream);


     int putc_unlocked(int c, FILE *stream);


     int putchar(int c);


     int putchar_unlocked(int c);


     int putw(int w, FILE *stream);


DESCRIPTION
     The fputc() function writes the byte specified  by  c  (con-
     verted  to an unsigned char) to the output stream pointed to
     by stream, at  the  position  indicated  by  the  associated
     file-position  indicator  for  the  stream (if defined), and
     advances the indicator appropriately.  If  the  file  cannot
     support  positioning  requests,  or if the stream was opened
     with append mode, the byte is appended to the output stream.


     The st_ctime and st_mtime fields of the file will be  marked
     for  update  between the successful execution of fputc() and
     the next successful completion of a call  to  fflush(3C)  or
     fclose(3C)  on  the  same  stream  or  a call to exit(3C) or
     abort(3C).


     The putc() routine behaves like fputc(), except that  it  is
     implemented  as a macro. It runs faster than fputc(), but it
     takes up more space per invocation and its  name  cannot  be
     passed as an argument to a function call.


     The call putchar(c) is equivalent to  putc(c,  stdout).  The
     putchar() routine is implemented as a macro.





SunOS 5.11           Last change: 1 Nov 2003                    1






Standard C Library Functions                            fputc(3C)



     The  putc_unlocked()  and  putchar_unlocked()  routines  are
     variants  of putc() and putchar(), 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 putw() function writes the word (that is, type int) w to
     the output stream (at the position at which the file offset,
     if defined, is pointing). The size of a word is the size  of
     a  type  int and varies from machine to machine.  The putw()
     function neither assumes nor causes special alignment in the
     file.


     The st_ctime and st_mtime fields of the file will be  marked
     for  update  between  the successful execution of putw() and
     the next successful completion of a call  to  fflush(3C)  or
     fclose(3C)  on  the  same  stream  or  a call to exit(3C) or
     abort(3C).

RETURN VALUES
     Upon     successful     completion,     fputc(),     putc(),
     putc_unlocked(),  putchar(),  and  putchar_unlocked() return
     the value that  was  written.   Otherwise,  these  functions
     return  EOF,  the error indicator for the stream is set, and
     errno is set to indicate the error.


     Upon successful completion, putw() returns 0. Otherwise,  it
     returns  a  non-zero value, sets the error indicator for the
     associated stream, and sets errno to indicate the error.


     An unsuccessful completion will occur, for example,  if  the
     file  associated  with  stream is not open for writing or if
     the output file cannot grow.

ERRORS
     The    fputc(),    putc(),    putc_unlocked(),    putchar(),
     putchar_unlocked(), and putw() functions will fail if either
     the stream is unbuffered or the stream's buffer needs to  be
     flushed, and:

     EAGAIN    The O_NONBLOCK flag is set for the file descriptor
               underlying stream and the process would be delayed
               in the write operation.


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



SunOS 5.11           Last change: 1 Nov 2003                    2






Standard C Library Functions                            fputc(3C)



     EFBIG     An attempt was  made  to  write  to  a  file  that
               exceeds  the  maximum  file  size  or the process'
               file size limit.


     EFBIG     The file is a regular file and an attempt was made
               to write at or beyond the offset maximum.


     EINTR     The write 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 a member of a background process group attempt-
               ing to write to its controlling  terminal,  TOSTOP
               is set, the process is neither ignoring nor block-
               ing SIGTTOU and the process group of  the  process
               is orphaned. This error may also be returned under
               implementation-dependent conditions.


     ENOSPC    There was no free space remaining  on  the  device
               containing the file.


     EPIPE     An attempt is made to write to a pipe or FIFO that
               is  not open for reading by any process. A SIGPIPE
               signal will also be sent to the calling thread.



     The    fputc(),    putc(),    putc_unlocked(),    putchar(),
     putchar_unlocked(), and putw() 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
     Functions exist for the putc(), putc_unlocked(),  putchar(),
     and putchar_unlocked() macros. To get the function form, the
     macro name must be undefined (for example, #undef putc).


     When the macro forms are used,  putc()  and  putc_unlocked()
     evaluate  the stream argument more than once. In particular,
     putc(c, *f++); does not work sensibly.  The fputc() function



SunOS 5.11           Last change: 1 Nov 2003                    3






Standard C Library Functions                            fputc(3C)



     should  be  used instead when evaluating the stream argument
     has side effects.


     Because of possible differences in word length and byte ord-
     ering,   files  written  using  putw()  are  implementation-
     dependent, and possibly cannot be read using getw(3C)  by  a
     different  application or by the same application running in
     a different environment.


     The putw() function is inherently byte stream  oriented  and
     is  not tenable in the context of either multibyte character
     streams or wide-character streams.  Application  programmers
     are  encouraged  to  use  one  of the character-based output
     functions instead.

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



     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  Interface Stability        |  fputc(),            putc(),|
   |                             |  putc_unlocked(), putchar(),|
   |                             |  and putchar_unlocked()  are|
   |                             |  Standard.                  |
   |_____________________________|_____________________________|
   | MT-Level                    | See NOTES below.            |
   |_____________________________|_____________________________|


SEE ALSO
     getrlimit(2),  ulimit(2)  write(2),   Intro(3),   abort(3C),
     exit(3C), fclose(3C), ferror(3C), fflush(3C), flockfile(3C),
     printf(3C),  putc(3C),  puts(3C),   setbuf(3C),   stdio(3C),
     attributes(5), standards(5)

NOTES
     The fputc(), putc(), putchar(), and putw() routines are  MT-
     Safe in multithreaded applications.  The putc_unlocked() and
     putchar_unlocked()  routines  are  unsafe  in  multithreaded
     applications.









SunOS 5.11           Last change: 1 Nov 2003                    4