.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "IBV_GET_DEVICE_LIST" "3" "2006-10-31" "libibverbs" "Libibverbs Programmer\[cq]s Manual"
.hy
.SH NAME
.PP
ibv_get_device_list, ibv_free_device_list - get and release list of
available RDMA devices
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <infiniband/verbs.h>

struct ibv_device **ibv_get_device_list(int *num_devices);

void ibv_free_device_list(struct ibv_device **list);
\f[R]
.fi
.SH DESCRIPTION
.PP
\f[B]ibv_get_device_list()\f[R] returns a NULL-terminated array of RDMA
devices currently available.
The argument \f[I]num_devices\f[R] is optional; if not NULL, it is set
to the number of devices returned in the array.
.PP
\f[B]ibv_free_device_list()\f[R] frees the array of devices
\f[I]list\f[R] returned by \f[B]ibv_get_device_list()\f[R].
.SH RETURN VALUE
.PP
\f[B]ibv_get_device_list()\f[R] returns the array of available RDMA
devices, or sets \f[I]errno\f[R] and returns NULL if the request fails.
If no devices are found then \f[I]num_devices\f[R] is set to 0, and
non-NULL is returned.
.PP
\f[B]ibv_free_device_list()\f[R] returns no value.
.SH ERRORS
.TP
\f[B]EPERM\f[R]
Permission denied.
.TP
\f[B]ENOSYS\f[R]
No kernel support for RDMA.
.TP
\f[B]ENOMEM\f[R]
Insufficient memory to complete the operation.
.SH NOTES
.PP
Client code should open all the devices it intends to use with
\f[B]ibv_open_device()\f[R] before calling
\f[B]ibv_free_device_list()\f[R].
Once it frees the array with \f[B]ibv_free_device_list()\f[R], it will
be able to use only the open devices; pointers to unopened devices will
no longer be valid.
.PP
Setting the environment variable \f[B]IBV_SHOW_WARNINGS\f[R] will cause
warnings to be emitted to stderr if a kernel verbs device is discovered,
but no corresponding userspace driver can be found for it.
.SH STATIC LINKING
.PP
If \f[B]libibverbs\f[R] is statically linked to the application then all
provider drivers must also be statically linked.
The library will not load dynamic providers when static linking is used.
.PP
To link the providers set the \f[B]RDMA_STATIC_PROVIDERS\f[R] define to
the comma separated list of desired providers when compiling the
application.
The special keyword `all' will statically link all supported
\f[B]libibverbs\f[R] providers.
.PP
This is intended to be used along with \f[B]pkg-config(1)\f[R] to setup
the proper flags for \f[B]libibverbs\f[R] linking.
.PP
If this is not done then \f[B]ibv_get_device_list\f[R] will always
return an empty list.
.PP
Using only dynamic linking for \f[B]libibverbs\f[R] applications is
strongly recommended.
.SH SEE ALSO
.PP
\f[B]ibv_fork_init\f[R](3), \f[B]ibv_get_device_guid\f[R](3),
\f[B]ibv_get_device_name\f[R](3), \f[B]ibv_get_device_index\f[R](3),
\f[B]ibv_open_device\f[R](3)
.SH AUTHOR
.PP
Dotan Barak <dotanba@gmail.com>