SYNOPSIS

    #include "libut/ut.h"
    int UT_fd_cntl(int fd, int op, ...);

DESCRIPTION

This function gets or sets ancillary state about file descriptor fd, which must have been previously registered using UT_fd_reg(3) or created using UT_net_connect(3). The op argument must be one of these pre-defined constants:

UTFD_GET_FLAGS

Retrieve the file descriptor flags and store them in the int* provided as the next argument. The bits in the integer that are valid to test are:

     UTFD_PIPE              /* type passed to UT_fd_reg(3)        */
     UTFD_SOCKET            /* type passed to UT_fd_reg(3)        */
     UTFD_OTHER             /* type passed to UT_fd_reg(3)        */
     UTFD_R                 /* callback invoked when readable     */
     UTFD_W                 /* callback invoked when writable     */
     UTFD_SOCKET_LISTENING  /* disposition passed to UT_fd_reg(3) */
     UTFD_SOCKET_ACCEPTED   /* disposition passed to UT_fd_reg(3) */
     UTFD_SOCKET_CONNECTING /* disposition passed to UT_fd_reg(3) */
     UTFD_SOCKET_CONNECTED  /* disposition passed to UT_fd_reg(3) */
     UTFD_SOCKET_LOCALADDR  /* aux data contains local address    */
     UTFD_SOCKET_REMOTEADDR /* aux data contains remote address   */
     UTFD_WRITE_PENDING     /* data being written when writable   */

UTFD_SET_FLAGS

Set the file descriptor flags according to the int provided as the next argument. This should only be used to modify a particular flag, like this:

            UT_fd_cntl(fd, UTFD_GET_FLAGS, &f);
            f |= UTFD_CLOSE_AFTER_WRITE;
            UT_fd_cntl(fd, UTFD_SET_FLAGS, f);

The only flag that should be set using this method is UTFD_CLOSE_AFTER_WRITE (which specifies that the file descriptor should be closed and unregistered after the subsequent UT_fd_write(3) completes, which may not be immediately).

For socket file descriptors, this function be used to alter the disposition flags, by clearing the UTFD_SOCKET_CONNECTING flag and setting UTFD_SOCKET_CONNECTED. (Normally this is handled automatically if UT_net_connect(3) is used).

UTFD_GET_DATA

Retrieve the opaque data pointer that is passed to the file descriptor's I/O callback. It is placed in the void** which is the next argument.

UTFD_SET_DATA

Set the opaque data pointer that is passed to the file descriptor's I/O callback to the void* which is the next argument.

UTFD_GET_AUX

Retrieve the ``auxiliary'' information about the file descriptor, currently applicable only to socket file descriptors and containing the local and remote IP address and port number (if UTFD_SOCKET_LOCALADDR and UTFD_SOCKET_REMOTEADDR are set in the flags, respectively). The internal UT_fd_aux_type structure is copied to the location specified by the next argument, of type UT_fd_aux_type*. The definition of UT_fd_aux_type is in libut/ut.h.

UTFD_SET_AUX

Set the ``auxiliary'' information about the file descriptor, currently applicable only to socket file descriptors and containing the local and remote IP address and port number (if UTFD_SOCKET_LOCALADDR and UTFD_SOCKET_REMOTEADDR are set in the flags, respectively). The UT_fd_aux_type structure, whose address is passed as the next argument of type UT_fd_aux_type*, is copied to libut's internal structure for the file descriptor. The definition of UT_fd_aux_type is in libut/ut.h.

RETURN VALUE

This functions returns 0 on success. On error, -1 is returned. An invalid file descriptor fd or invalid op are errors.

SEE ALSO

UT_fd_reg(3), UT_fd_unreg(3), UT_fd_write(3)

AUTHOR

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