---
name: "fduserdata"
section: "3"
platform: "linux"
package: "libfduserdata-dev"
version: "0.1.2-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/fduserdata"
---

# fduserdata(3)

associate file descriptors with user defined data

## NAME

fduserdata\_create, fduserdata\_destroy, fduserdata\_destroy\_cb, fduserdata\_new, fduserdata\_get, fduserdata\_put, fduserdata\_del - associate file descriptors with user defined data

## SYNOPSIS

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

**FDUSERDATA \*fduserdata\_create(int** *size***);**

**void fduserdata\_destroy(FDUSERDATA \****fdtable***);**

**typedef void (\*fduserdata\_destr\_cb\_t)(int fd, void \*data, void \*arg);**\
 **void fduserdata\_destroy\_cb(FDUSERDATA \****fdtable***, fduserdata\_destr\_cb\_t** *callback***, void \****arg***);**

**void \*fduserdata\_new(FDUSERDATA \****fdtable***, int** *fd***,** *type***);**

**void \*fduserdata\_get(FDUSERDATA \****fdtable***, int** *fd***);**

**void fduserdata\_put(void \****data***);**

**int fduserdata\_del(void \****data***);**

## DESCRIPTION

This library permits one to associate file descriptors with user defined data, more precisely it manages a data structure whose searching key is a file descriptor.

**fduserdata\_create** and **fduserdata\_destroy** are the constructor and destructor of the data structure, respectively. The data structure has been implemented as a hash table, the argument *size* of **fduserdata\_create** is the size of the hash array. When *size* is zero the hash array has its default size (64).

**fduserdata\_destroy\_cb** is an alternative destructor which calls the function *callback* for each element still in the data structure.

**fduserdata\_new** creates a new element. It is a macro: *type* is the type of the user data.

**fduserdata\_get** search the user data associated to the *fd*.

Both **fduserdata\_new** and **fduserdata\_get** lock the access to the element, so that fduserdata is thread safe. **fduserdata\_put** unlocks the element and makes it available for further requests.

**fduserdata\_del** can be used instead of **fduserdata\_put** to delete the element.

## RETURN VALUE

**fduserdata\_create** returns the descriptor of the data structure (NULL in case of error).

**fduserdata\_new** returns the element of type *type* just created (NULL in case of error).

**fduserdata\_get** returns the element or NULL if no data corresponds to the file descriptor *fd*.

**fduserdata\_del** On success, zero is returned. On error, -1 is returned.

On error, *errno* is set appropriately.

## EXAMPLE

```
fduserdata uses a trivial hash table, the optional arg is the
size of the hash table: default value = 64
    FDUSERDATA table = fduserdata_create(0);
    struct mydata {
    // fd data fields ...
    };
create a struct mydata for the file descriptor fd.
    struct mydata *data = fduserdata_new(table, fd, struct mydata);
.... set user defined data (data->fields)
    fduserdata_put(data);
search for data
there is mutual exclusion between new/put, get/put (or new/del, get/del)
so do not insert time consuming or blocking ops.
    struct mydata *fddata = fduserdata_get(table, fd);
    if (fddata) {
... read/update user defined data (data->fields)
(use fduserdata_del instead of fduserdata_put to delete the element)
          fduserdata_put(data);
    }
at the end... when table is no longer required
    fduserdata_destroy(table);
```

## AUTHOR

VirtualSquare. Project leader: Renzo Davoli.