putc_unlocked(3C)




NAME

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


SYNOPSIS

     #include <stdio.h>

     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.

     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.

     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 attempting to
           write to its controlling terminal, TOSTOP is set,  the
           process  is  neither ignoring nor blocking 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  con-
           taining 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 process.

     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
     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.

     When a UFS file system is mounted with logging enabled, file
     system  transactions  that  free blocks from files might not
     actually add those freed blocks to the  file  system's  free
     list  until  some  unspecified  time  in  the  future.  This
     behavior improves file system performance but does not  con-
     form  to the POSIX, Single UNIX Specification, SPARC Confor-
     mance Definition, System  V  Application  Binary  Interface,
     System  V Interface Definition, and X/Open Portability Guide
     Standards, which  require  that  freed  space  be  available
     immediately.  To enable standards conformance regarding file
     deletions or to address the problem of  not  being  able  to
     grow  files  on a relatively full UFS file system even after
     files  have  been  deleted,   disable   UFS   logging   (see
     mount_ufs(1M).


ATTRIBUTES

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

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | See NOTES below.            |
    |_____________________________|_____________________________|


SEE ALSO

     mount_ufs(1M), getrlimit(2), ulimit(2)  write(2),  intro(3),
     abort(3C),  exit(3C),  fclose(3C),  ferror(3C),  fflush(3C),
     flockfile(3C), fopen(3UCB),  printf(3C), putc(3C), puts(3C),
     setbuf(3C), stdio(3C), attributes(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.


Man(1) output converted with man2html