Back to libut API Reference


SYNOPSIS

    #include "libut/ut.h"
    int UT_fd_write(int fd, void *buffer, size_t len);


DESCRIPTION

This function writes len bytes from buffer to file descriptor fd, like write(2), but with this added functionality: if fewer than len bytes can be written immediately, the remaining bytes are copied to a pending-output buffer and written in the libut event loop as fd becomes writable.

If pending output for the file descriptor already exists when this function is called, the buffer is appended to the existing pending-output buffer. Thus, successive calls to this function can be made; the writes will take place in order.

While the libut event loop waits for a file descriptor to become writable in order to write buffered output, it handles other events. That is to say, using this function permits arbitrary-length writes to arbitrarily-slow (or fast) receivers without causing performance of any other I/O or event handling to suffer.

The file descriptor fd must have been previously registered using UT_fd_reg(3). This happens automatically for file descriptors created using UT_net_connect(3).


RETURN VALUE

This function returns -1 on an error. On success, a non-negative number is returned, which indicates how many bytes were immediately written. If this is less than len, it implies that the remaining bytes are buffered to be written as file descriptor fd becomes writable.


RELATED CONTROL PORT COMMANDS

The fds control port command displays a 'W' flag for file descriptors having data in their pending-output buffer.


SEE ALSO

UT_fd_reg(3), UT_fd_unreg(3), UT_fd_cntl(3), UT_fd_get_aux(3)


AUTHOR

Troy D. Hanson <thanson@users.sourceforge.net>