Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
io_trywrite(3)		   Library Functions Manual		io_trywrite(3)

       io_trywrite - write to a	descriptor without blocking

       #include	<io.h>

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

       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 as-
	  sume that io_trywrite	always succeeds	in writing exactly len bytes.

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

       o  io_trywrite returns -3, setting errno	to something  other  than  EA-
	  GAIN:	No bytes were written, because the write attempt encountered a
	  persistent error, such as a serious disk failure (EIO), an  unreach-
	  able 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 con-
       tinue  writing,	rather than exiting with an appropriate	exit code. The
       UNIX kernel developers decided to send a	SIGPIPE	signal,	 which	termi-
       nates  the  process by default, along with returning EPIPE. This	papers
       over the	problem	without	fixing it: the same programs ignore other  er-
       rors  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.

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



Want to link to this manual page? Use this URL:

home | help