---
name: "rte_fbarray_find_next_free"
section: "3"
platform: "linux"
package: "dpdk-doc"
version: "24.11.4-0+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rte_fbarray.h"
---

# rte\_fbarray\_find\_next\_free(3)

Part of [rte\_fbarray.h(3)](/rte_fbarray.h/3.md).

## NAME

rte\_fbarray.h

## SYNOPSIS

`#include <stdio.h>`\
 `#include <rte_rwlock.h>`\

### Functions

int **rte\_fbarray\_init** (struct rte\_fbarray \*arr, const char \*name, unsigned int len, unsigned int elt\_sz)\
 int **rte\_fbarray\_attach** (struct rte\_fbarray \*arr)\
 int **rte\_fbarray\_destroy** (struct rte\_fbarray \*arr)\
 int **rte\_fbarray\_detach** (struct rte\_fbarray \*arr)\
 void \* **rte\_fbarray\_get** (const struct rte\_fbarray \*arr, unsigned int idx)\
 int **rte\_fbarray\_find\_idx** (const struct rte\_fbarray \*arr, const void \*elt)\
 int **rte\_fbarray\_set\_used** (struct rte\_fbarray \*arr, unsigned int idx)\
 int **rte\_fbarray\_set\_free** (struct rte\_fbarray \*arr, unsigned int idx)\
 int **rte\_fbarray\_is\_used** (struct rte\_fbarray \*arr, unsigned int idx)\
 int **rte\_fbarray\_find\_next\_free** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_next\_used** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_next\_n\_free** (struct rte\_fbarray \*arr, unsigned int start, unsigned int n)\
 int **rte\_fbarray\_find\_next\_n\_used** (struct rte\_fbarray \*arr, unsigned int start, unsigned int n)\
 int **rte\_fbarray\_find\_contig\_free** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_contig\_used** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_prev\_free** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_prev\_used** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_prev\_n\_free** (struct rte\_fbarray \*arr, unsigned int start, unsigned int n)\
 int **rte\_fbarray\_find\_prev\_n\_used** (struct rte\_fbarray \*arr, unsigned int start, unsigned int n)\
 int **rte\_fbarray\_find\_rev\_contig\_free** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_rev\_contig\_used** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_biggest\_free** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_biggest\_used** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_rev\_biggest\_free** (struct rte\_fbarray \*arr, unsigned int start)\
 int **rte\_fbarray\_find\_rev\_biggest\_used** (struct rte\_fbarray \*arr, unsigned int start)\
 void **rte\_fbarray\_dump\_metadata** (struct rte\_fbarray \*arr, FILE \*f)\

## Detailed Description

File-backed shared indexed array for DPDK.

Basic workflow is expected to be the following: 1) Allocate array either using **rte\_fbarray\_init() or rte\_fbarray\_attach() (depending on whether it's shared between multiple DPDK processes) 2) find free spots using rte\_fbarray\_find\_next\_free() 3) get pointer to data in the free spot using rte\_fbarray\_get(), and copy data into the pointer (element size is fixed) 4) mark entry as used using rte\_fbarray\_set\_used()**

**Calls to rte\_fbarray\_init() and rte\_fbarray\_destroy() will have consequences for all processes, while calls to rte\_fbarray\_attach() and rte\_fbarray\_detach() will only have consequences within a single process. Therefore, it is safe to call rte\_fbarray\_attach() or rte\_fbarray\_detach() while another process is using** `rte_fbarray`**, provided no other thread within the same process will try to use** `rte_fbarray` **before attaching or after detaching. It is not safe to call rte\_fbarray\_init() or rte\_fbarray\_destroy() while another thread or another process is using** `rte_fbarray`**.**

**Definition in file rte\_fbarray.h.**

## Function Documentation

### int rte\_fbarray\_init (struct rte\_fbarray \* arr, const char \* name, unsigned int len, unsigned int elt\_sz)

**Set up** `rte_fbarray` **structure and allocate underlying resources.**

**Call this function to correctly set up** `rte_fbarray` **and allocate underlying files that will be backing the data in the current process. Note that in order to use and share** `rte_fbarray` **between multiple processes, data pointed to by** `arr` **pointer must itself be allocated in shared memory.**

**Parameters**

*arr* **Valid pointer to allocated** `rte_fbarray` **structure.**\
 *name* **Unique name to be assigned to this array.**\
 *len* **Number of elements initially available in the array.**\
 *elt\_sz* **Size of each element.**

**Returns**

- •

  **0 on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_attach (struct rte\_fbarray \* arr)

**Attach to a file backing an already allocated and correctly set up** `rte_fbarray` **structure.**

**Call this function to attach to file that will be backing the data in the current process. The structure must have been previously correctly set up with a call to rte\_fbarray\_init(). Calls to rte\_fbarray\_attach() are usually meant to be performed in a multiprocessing scenario, with data pointed to by** `arr` **pointer allocated in shared memory.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up rte\_fbarray structure.**

**Returns**

- •

  **0 on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_destroy (struct rte\_fbarray \* arr)

**Deallocate resources for an already allocated and correctly set up** `rte_fbarray` **structure, and remove the underlying file.**

**Call this function to deallocate all resources associated with an** `rte_fbarray` **structure within the current process. This will also zero-fill data pointed to by** `arr` **pointer and remove the underlying file backing the data, so it is expected that by the time this function is called, all other processes have detached from this** `rte_fbarray`**.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**

**Returns**

- •

  **0 on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_detach (struct rte\_fbarray \* arr)

**Deallocate resources for an already allocated and correctly set up** `rte_fbarray` **structure.**

**Call this function to deallocate all resources associated with an** `rte_fbarray` **structure within current process.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**

**Returns**

- •

  **0 on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### void \* rte\_fbarray\_get (const struct rte\_fbarray \* arr, unsigned int idx)

**Get pointer to element residing at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *idx* **Index of an element to get a pointer to.**

**Returns**

- •

  **non-NULL pointer on success.**

- •

  **NULL on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_idx (const struct rte\_fbarray \* arr, const void \* elt)

**Find index of a specified element within the array.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *elt* **Pointer to element to find index to.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_set\_used (struct rte\_fbarray \* arr, unsigned int idx)

**Mark specified element as used.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *idx* **Element index to mark as used.**

**Returns**

- •

  **0 on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_set\_free (struct rte\_fbarray \* arr, unsigned int idx)

**Mark specified element as free.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *idx* **Element index to mark as free.**

**Returns**

- •

  **0 on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_is\_used (struct rte\_fbarray \* arr, unsigned int idx)

**Check whether element at specified index is marked as used.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *idx* **Element index to check as used.**

**Returns**

- •

  **1 if element is used.**

- •

  **0 if element is unused.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_next\_free (struct rte\_fbarray \* arr, unsigned int start)

**Find index of next free element, starting at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_next\_used (struct rte\_fbarray \* arr, unsigned int start)

**Find index of next used element, starting at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_next\_n\_free (struct rte\_fbarray \* arr, unsigned int start, unsigned int n)

**Find index of next chunk of** `n` **free elements, starting at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**\
 *n* **Number of free elements to look for.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_next\_n\_used (struct rte\_fbarray \* arr, unsigned int start, unsigned int n)

**Find index of next chunk of** `n` **used elements, starting at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**\
 *n* **Number of used elements to look for.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_contig\_free (struct rte\_fbarray \* arr, unsigned int start)

**Find how many more free entries there are, starting at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_contig\_used (struct rte\_fbarray \* arr, unsigned int start)

**Find how many more used entries there are, starting at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_prev\_free (struct rte\_fbarray \* arr, unsigned int start)

**Find index of previous free element, starting at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_prev\_used (struct rte\_fbarray \* arr, unsigned int start)

**Find index of previous used element, starting at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_prev\_n\_free (struct rte\_fbarray \* arr, unsigned int start, unsigned int n)

**Find lowest start index of chunk of** `n` **free elements, down from specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**\
 *n* **Number of free elements to look for.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_prev\_n\_used (struct rte\_fbarray \* arr, unsigned int start, unsigned int n)

**Find lowest start index of chunk of** `n` **used elements, down from specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**\
 *n* **Number of used elements to look for.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_rev\_contig\_free (struct rte\_fbarray \* arr, unsigned int start)

**Find how many more free entries there are before specified index (like** `rte_fbarray_find_contig_free` **but going in reverse).**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_rev\_contig\_used (struct rte\_fbarray \* arr, unsigned int start)

**Find how many more used entries there are before specified index (like** `rte_fbarray_find_contig_used` **but going in reverse).**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_biggest\_free (struct rte\_fbarray \* arr, unsigned int start)

**Find index of biggest chunk of free elements, starting at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_biggest\_used (struct rte\_fbarray \* arr, unsigned int start)

**Find index of biggest chunk of used elements, starting at specified index.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_rev\_biggest\_free (struct rte\_fbarray \* arr, unsigned int start)

**Find index of biggest chunk of free elements before a specified index (like** `rte_fbarray_find_biggest_free`**, but going in reverse).**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### int rte\_fbarray\_find\_rev\_biggest\_used (struct rte\_fbarray \* arr, unsigned int start)

**Find index of biggest chunk of used elements before a specified index (like** `rte_fbarray_find_biggest_used`**, but going in reverse).**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *start* **Element index to start search from.**

**Returns**

- •

  **non-negative integer on success.**

- •

  **-1 on failure, with** `rte_errno` **indicating reason for failure.**

### void rte\_fbarray\_dump\_metadata (struct rte\_fbarray \* arr, FILE \* f)

**Dump** `rte_fbarray` **metadata.**

**Parameters**

*arr* **Valid pointer to allocated and correctly set up** `rte_fbarray` **structure.**\
 *f* **File object to dump information into.**

## Author

**Generated automatically by Doxygen for DPDK from the source code.**