io_trywrite(3) [debian man page]

io_trywrite(3)						     Library Functions Manual						    io_trywrite(3)

NAME

       io_trywrite - write to a descriptor without blocking

SYNTAX

       #include <io.h>

       int io_trywrite(int64 fd,const char* buf,int64 len);

DESCRIPTION

       io_trywrite  tries to write len bytes of data from buf[0], buf[1], ..., buf[len-1] to descriptor fd. (The effects are undefined if len is 0
       or smaller.) There are several possible results:

       o  o_trywrite returns an integer between 1 and len: This number of bytes was immediately written from the beginning of buf.  Note that this
	  number can be, and often is, smaller than len; you must not assume that io_trywrite always succeeds in writing exactly len bytes.

       o  io_trywrite returns -1, setting errno to EAGAIN: No bytes were written, because the descriptor is not ready. For example, the descriptor
	  is writing to a full pipe that could still be read.

       o  io_trywrite returns -3, setting errno to something other than EAGAIN: No bytes were written, because the  write  attempt  encountered  a
	  persistent error, such as a serious disk failure (EIO), an unreachable network (ENETUNREACH), or an invalid descriptor number (EBADF).

       io_trywrite does not pause waiting for a descriptor that is not ready.  If you want to pause, use io_waitread or io_wait.

       You can make io_trywrite faster and more efficient by making the socket non-blocking with io_nonblock().

       Once  upon  a time, many UNIX programs neglected to check the success of their writes. They would often encounter EPIPE, and would blithely
       continue writing, rather than exiting with an appropriate exit code. The UNIX kernel developers decided to send	a  SIGPIPE  signal,  which
       terminates  the	process  by  default, along with returning EPIPE. This papers over the problem without fixing it: the same programs ignore
       other errors such as EIO. One hopes that the programs have been fixed by now; kernels nevertheless continue to generate the SIGPIPE signal.
       The  first time io_trywrite or io_waitwrite is called, it arranges for SIGPIPE to be ignored.  (Technically, for SIGPIPE to be caught by an
       empty signal handler, so this doesn't affect child processes.) Do not use SIGPIPE elsewhere in the program.

SEE ALSO

       io_nonblock(3), io_waitread(3), io_trywritetimeout(3)

																    io_trywrite(3)

SENDFILE(2)						      BSD System Calls Manual						       SENDFILE(2)

NAME

     sendfile -- send a file to a socket

SYNOPSIS

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

     int
     sendfile(int fd, int s, off_t offset, off_t *len, struct sf_hdtr *hdtr, int flags);

DESCRIPTION

     The sendfile() system call sends a regular file specified by descriptor fd out a stream socket specified by descriptor s.

     The offset argument specifies where to begin in the file.	Should offset fall beyond the end of file, the system will return success and
     report 0 bytes sent as described below.

     The len argument is a value-result parameter, that specifies how many bytes of the file should be sent and/or how many bytes have been sent.
     Initially the value pointed to by the len argument specifies how many bytes should be sent with 0 having the special meaning to send until
     the end of file has been reached.	On return the value pointed to by the len argument indicates how many bytes have been sent, except when a
     header or trailer is specified as shown below.  The len pointer may not be NULL.

     An optional header and/or trailer can be sent before and after the file data by specifying a pointer to a struct sf_hdtr, which has the fol-
     lowing structure:

	   struct sf_hdtr {
		   struct iovec *headers;  /* pointer to header iovecs */
		   int hdr_cnt; 	   /* number of header iovecs */
		   struct iovec *trailers; /* pointer to trailer iovecs */
		   int trl_cnt; 	   /* number of trailer iovecs */
	   };

     The headers and trailers pointers, if non-NULL, point to arrays of struct iovec structures.  See the writev() system call for information on
     the iovec structure.  The number of iovecs in these arrays is specified by hdr_cnt and trl_cnt.

     When a header or trailer is specified, the value of len argument indicates the maximum number of bytes in the header and/or file to be sent.
     It does not control the trailer; if a trailer exists, all of it will be sent.  If the value of len argument is 0, all of the header and/or
     file will be sent before the entire trailer is sent.  On return, the len argument specifies the total number of bytes sent.

     The flags parameter is reserved for future expansion and must be set to 0. Any other value will cause sendfile() to return EINVAL.

     When using a socket marked for non-blocking I/O, sendfile() may send fewer bytes than requested.  In this case, the number of bytes success-
     fully sent is returned in the via the len parameters and the error EAGAIN is returned.

     When a signal causes sendfile() to return the error EINTR, the len argument may return 0 without necessarily meaning the end of file has been
     reached as the signal may have been caught before any data was sent.

IMPLEMENTATION NOTES

     The Mac OS X implementation of sendfile() uses 64 bits types for size and offset parameters so there is no need for a 64 bits version
     sendfile64() as found on some other operating systems.

RETURN VALUES

     The sendfile() function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indi-
     cate the error.

     The number of bytes sent is returned via the parameter len.  A value of 0 means the end of the file specified by descriptor fd has been
     reached or that the value passed in offset falls beyond the end of file.

ERRORS

     [EAGAIN]		The socket is marked for non-blocking I/O and not all data was sent due to the socket buffer being full.  If specified,
			the number of bytes successfully sent will be returned in *len.

     [EBADF]		The fd argument is not a valid file descriptor.

     [ENOTSUP]		The fd argument does not refer to a regular file.

     [EBADF]		The s argument is not a valid socket descriptor.

     [ENOTSOCK] 	The s argument does not refer stream oriented socket.

     [EFAULT]		An invalid address was specified for an argument.

     [EINTR]		A signal interrupted sendfile() before it could be completed.  If specified, the number of bytes successfully sent will be
			returned in *len.

     [EINVAL]		The offset argument is negative.

     [EINVAL]		The len argument is NULL.

     [EINVAL]		The flags argument is not set to 0.

     [EIO]		An error occurred while reading from fd.

     [ENOTCONN] 	The s argument points to an unconnected socket.

     [ENOTSOCK] 	The s argument is not a socket.

     [EOPNOTSUPP]	The file system for descriptor fd does not support sendfile().

     [EPIPE]		The socket peer has closed the connection.

SEE ALSO

     open(2), send(2), socket(2), writev(2)

HISTORY

     The sendfile() system call first appeared in Darwin 9.0 (Mac OS X version 10.5) .

AUTHORS

     This manual page is based on the FreeBSD version written by David G. Lawrence <dg@dglawrence.com>

Mac OS X							  March 31, 2006							  Mac OS X