.\" Copyright 2015-2017 IBM Corp.
.\"
.TH CXL_ADAPTER_NEXT 3 2017-05-24 "LIBCXL 1.5" "CXL Programmer's Manual"
.SH NAME
cxl_adapter_next \- iterate to the next CXL adapter
.PP
cxl_for_each_adapter \- iteration macro
.SH SYNOPSIS
.B #include <libcxl.h>
.PP
.B "struct cxl_adapter_h *cxl_adapter_next(struct cxl_adapter_h"
.BI * adapter );
.SH DESCRIPTION
.BR cxl_adapter_next ()
returns an adapter handle describing the next available CXL
adapter.
.PP
When
.I adapter
is NULL, then an adapter handle is allocated, and the first available
adapter is returned.
.PP
When
.I adapter
is the last CXL adapter available, then the adapter handle is freed,
.I errno
is set to zero, and NULL is returned.
Alternatively, the adapter handle can be freed explicitly with
.BR cxl_adapter_free ().
.SH RETURN VALUE
On success, an adapter handle is returned, or NULL is returned and
.I errno
is set to zero.
On error, NULL is returned, and
.I errno
is set appropriately.
.SH ERRORS
.TP
.B ENODEV
Unsupported kernel CXL API.
.TP
.B ENOMEM
Insufficient memory.
.SH EXAMPLE
The CXL library provides the following macro to enumerate all
CXL adapters:
.PP
.nf
    #define cxl_for_each_adapter(adapter) \\
        for (adapter = cxl_adapter_next(NULL); adapter; \\
             adapter = cxl_adapter_next(adapter))
.fi
.SH SEE ALSO
.BR cxl (3),
.BR cxl_adapter_afu_next (3),
.BR cxl_adapter_dev_name (3),
.BR cxl_adapter_free (3),
.BR cxl_afu_next (3),
.BR cxl_get_base_image (3),
.BR cxl_get_caia_version (3),
.BR cxl_get_image_loaded (3),
.BR cxl_get_psl_revision (3),
.BR cxl_get_psl_timebase_synced (3),
.BR cxl_get_tunneled_ops_supported (3)