write man page on NeXTSTEP

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


WRITE(2)							      WRITE(2)

NAME
       write - write output

BSD SYNOPSIS
       int write(int fd, char *buf, int nbytes);

       #include <sys/types.h>
       #include <sys/uio.h>

       int writev(int fd, struct iovec *iov, int iovcnt);

POSIX SYNOPSIS
       size_t write(int fd, const void *buf, size_t nbytes);

DESCRIPTION
       The  write  function  attempts  to  write  nbytes of data to the object
       referenced by the descriptor fd from the buffer pointed to by buf.

       With objects capable of seeking, write starts at a  position  given  by
       the  seek  pointer associated with fd (see lseek(2)).  Upon return, the
       seek pointer for fd is incremented by  the  number  of  bytes  actually
       written.

       Objects	that  are not capable of seeking always write from the current
       position.  The value of the pointer associated with such an  object  is
       undefined.

       If the real user is not the super-user, then write clears the set-user-
       id bit on a file.  This prevents penetration of system  security	 by  a
       user  who  “captures”  a	 writable set-user-id file owned by the super-
       user.

       When using non-blocking I/O on objects such as sockets that are subject
       to flow control, write may write fewer bytes than requested; the return
       value must be noted, and the  remainder	of  the	 operation  should  be
       retried when possible.

       The  writev  function  performs	a scattered write, writing output data
       from the iovcnt buffers specified by the	 members  of  the  iov	array:
       iov[0],	iov[1],	 iov[  iovcnt - 1].  The return value of writev is the
       same as that for write.

       The iovec structure is defined as

	      struct iovec {
		   caddr_t   iov_base;
		   int	iov_len;
	      };

       Each iovec entry specifies the base address and length of  an  area  in
       memory where data should be written from.  Writev will always write all
       data from an area before proceeding to the  next.   POSIX  applications
       should not use writev.

       POSIX  applications  may	 expect the following additional behavior when
       attempting to write (but not writev) to a pipe or FIFO:

       (1)  There is no file offset associated with a pipe, hence  each	 write
	    request will append to the end of the pipe.

       (2)  Write  requests  of	 {PIPE_BUF}  bytes or less are not interleaved
	    with data from any other processes doing writes on the same	 pipe.
	    Writes of greater than {PIPE_BUF} bytes may have data interleaved,
	    on arbitrary boundaries, with writes by other  processes,  whether
	    or not the O_NONBLOCK flag of the file status flags is set.

       (3)  If	the  O_NONBLOCK	 flag  is clear, a write request may cause the
	    process to block, but on normal completion if will return nbyte.

       (4)  If the O_NONBLOCK flag is set,  write  requests  will  be  handled
	    differently, in the following ways:

	    (a)	 The write function will not block the process.

	    (b)	 A write request for {PIPE_BUF} or fewer bytes will:

		 [1]  If  there	 is  sufficient	 space	available in the pipe,
		      transfer all the data and return	the  number  of	 bytes
		      requested.

		 [2]  If  there is not sufficient space available in the pipe,
		      transfer no data and return -1 with errno set to EAGAIN.

	    (c)	 A write request for more than {PIPE_BUF} bytes will either:

		 [1]  When at least one byte can be written, transfer what  it
		      can  and	return	the number of bytes written.  When all
		      data previously written to the pipe has  been  read,  it
		      will transfer at least {PIPE_BUF} bytes.

		 [2]  When no data can be written, transfer no data and return
		      -1 with errno set to EAGAIN.

       POSIX applications may also expect the  following  when	attempting  to
       write  to  a  file descriptor (other than a pipe or FIFO) that supports
       nonblocking writes and cannot accept the data immediately:

       (1)  If the O_NONBLOCK flag is clear, write will not block the process.
	    If	some  data  can be written without blocking the process, write
	    will write what it can and return the  number  of  bytes  written.
	    Otherwise, it will return -1 and errno will be set to EAGAIN.

       (2)  If the O_NONBLOCK flag is set, write will block until the data can
	    be accepted.

RETURN VALUE
       Upon successful completion the number  of  bytes	 actually  written  is
       returned.   Otherwise a -1 is returned and the global variable errno is
       set to indicate the error.

ERRORS
       Write will fail and the file pointer will remain unchanged  if  one  or
       more of the following are true:

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

       [EBADF]	      fd is not a valid descriptor open for writing.

       [EPIPE]	      An attempt is made to write to a pipe that is  not  open
		      for  reading  by	any process; or, an attempt is made to
		      write to a  socket  of  type  SOCK_STREAM	 that  is  not
		      connected to a peer socket.

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

       [EFAULT]	      Part of the data to be written to the file lies  outside
		      the process's allocated address space.

       [EINVAL]	      The pointer associated with fd was negative.

       [ENOSPC]	      There  is	 no  free  space  remaining on the file system
		      containing the file.

       [EINTR]	      The write operation was interrupted by a signal, and  no
		      data was transferred.

       [EDQUOT]	      The  user's  quota  of  disk  blocks  on the file system
		      containing the file has been exhausted.

       [EIO]	      An I/O error occurred while reading from or  writing  to
		      the  file	 system;  or, the process is in the background
		      process  group  and  is  attempting  to  write  to   its
		      controlling  terminal,  TOSTOP  is  set,	the process is
		      neither ignoring nor blocking SIGTTOU signals,  and  the
		      process group of the process is orphaned.

       [EWOULDBLOCK]  The  file	 was  marked for non-blocking I/O, and no data
		      could be written immediately.

       In addition, writev may return one of the following errors:

       [EINVAL]	      Iovcnt was less than or equal to 0, or greater than  16;
		      or,  one	of  the	 iov_len  values  in the iov array was
		      negative; or, the sum of the iov_len values in  the  iov
		      array overflowed a 32-bit integer.

SEE ALSO
       creat(2), dup(2), fcntl(2), lseek(2), open(2), pipe(2)

				August 1, 1992			      WRITE(2)
[top]

List of man pages available for NeXTSTEP

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