---
name: "iv_fd"
section: "3"
platform: "linux"
package: "libivykis-dev"
version: "0.43.2-1+b1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/iv_fd"
---

# iv\_fd(3)

deal with ivykis file descriptors

## NAME

iv\_fd\_register, iv\_fd\_register\_try, iv\_fd\_unregister, iv\_fd\_registered, iv\_fd\_set\_handler\_in, iv\_fd\_set\_handler\_err, iv\_fd\_set\_handler\_out - deal with ivykis file descriptors

## SYNOPSIS

**#include \<iv.h\>**

```
struct iv_fd {
        int             fd;
        void            *cookie;
        void            (*handler_in)(void *);
        void            (*handler_out)(void *);
        void            (*handler_err)(void *);
};
```

**void IV\_FD\_INIT(struct iv\_fd \****fd***);**\
 **void iv\_fd\_register(struct iv\_fd \****fd***);**\
 **int iv\_fd\_register\_try(struct iv\_fd \****fd***);**\
 **void iv\_fd\_unregister(struct iv\_fd \****fd***);**\
 **int iv\_fd\_registered(const struct iv\_fd \****fd***);**\
 **void iv\_fd\_set\_handler\_in(struct iv\_fd \****fd***, void (\****handler***)(void \*));**\
 **void iv\_fd\_set\_handler\_out(struct iv\_fd \****fd***, void (\****handler***)(void \*));**\
 **void iv\_fd\_set\_handler\_err(struct iv\_fd \****fd***, void (\****handler***)(void \*));**\

## DESCRIPTION

The functions **iv\_fd\_register** and **iv\_fd\_unregister** register, respectively unregister, a file descriptor with the current thread's ivykis event loop.  Calling **iv\_fd\_registered** on a file descriptor returns true if that file descriptor is currently registered with ivykis.

When a file descriptor that is registered with ivykis becomes ready for input or output, or an error condition occurs on that file descriptor, and a callback function for that event has been specified, that callback function will be called in the thread that the file descriptor was registered in.

And conversely, when a file descriptor that is already ready for input or output or already has an error condition set is registered with ivykis, and the corresponding callback function pointer is not NULL, the callback function will be called in the next iteration of the current thread's ivykis event loop.

Before a file descriptor is registered, it must have been initialised by calling **IV\_FD\_INIT** on it, and must have had its **-\>fd** member field set to a valid OS file descriptor.  The **-\>handler\_in, -\>handler\_out** and **-\>handler\_err** member fields point to callback functions that are to be called when the specified file descriptor becomes ready for input or output or an error condition occurs.  If any handler function is set to **NULL,** it indicates that the application is not interested in being notified of the corresponding event.

An application is not allowed to change the **-\>fd** member while a file descriptor is registered.

**iv\_fd\_set\_handler\_in** changes the callback function to be called when descriptor **fd** becomes ready for input.  An application is not allowed to directly change the **-\>handler\_in** member after the file descriptor has been registered, this function has to be used instead.  Conversely, it is not allowed to use this function before the file descriptor has been registered.

**iv\_fd\_set\_handler\_out** is analogous to **iv\_fd\_set\_handler\_in,** only it deals with the callback function for output readiness **(-\>handler\_out).**

**iv\_fd\_set\_handler\_err** is analogous to **iv\_fd\_set\_handler\_in** and **iv\_fd\_set\_handler\_out,** only it deals with the callback function for error conditions **(-\>handler\_err).**

When a handler function was NULL, and was set to a non-NULL value by calling **iv\_fd\_set\_handler\_in, iv\_fd\_set\_handler\_out** or **iv\_fd\_set\_handler\_err,** and the file descriptor was already ready for input or output, or already had an error condition set, an event is generated, and the specified callback function will be called in the next iteration of the current thread's event loop.  The application does not need to poll the file descriptor to see if a condition was already raised.

Callback functions are passed a **cookie** value as their first and sole argument.  If the application wishes to use this facility for transferring data to the callback function, it should set the **-\>cookie** member of a file descriptor to a value of type **void \*.** This value can be modified directly by the application at any time without calling a helper function.

When a file descriptor is registered with ivykis, it is transparently set to nonblocking mode, and configured to be closed on [**exit**(3)](/exit/3.md).

An application is allowed to unregister a file descriptor from within any callback function, including callback functions triggered by that file descriptor itself, and even to free the memory corresponding to that file descriptor from any callback function, but a **struct iv\_fd** can only be unregistered in the thread that it was registered from.

It is allowed to register the same underlying OS file descriptor in multiple threads, but a given **struct iv\_fd** can only be registered in one thread at a time.

**iv\_fd\_register** does not return errors to the caller, and in case of an error while registering the file descriptor, for example if it isn't open or is unpollable, **iv\_fatal**(2) will be invoked.  If it is not known whether registering the file descriptor with the kernel will be successful or not, use **iv\_fd\_register\_try** instead, which is a variant on **iv\_fd\_register** which returns a nonzero value in case of a registration error. Since **iv\_fd\_register\_try** disables various internal optimisations, it is recommended to use **iv\_fd\_register** whenever possible.

See [**iv\_examples**(3)](/iv_examples/3.md) for programming examples.

## SEE ALSO

[**ivykis**(3)](/ivykis/3.md), [**iv\_examples**(3)](/iv_examples/3.md)