.\" Automatically generated by Pandoc 3.1.11.1
.\"
.TH "ibv_attach_counters_point_flow" "3" "2018\-04\-02" "libibverbs" "Libibverbs Programmer\[cq]s Manual"
.SH NAME
\f[B]ibv_attach_counters_point_flow\f[R] \- attach individual counter
definition to a flow object
.SH SYNOPSIS
.IP
.EX
#include <infiniband/verbs.h>

int ibv_attach_counters_point_flow(struct ibv_counters *counters,
                                   struct ibv_counter_attach_attr *counter_attach_attr,
                                   struct ibv_flow *flow);
.EE
.SH DESCRIPTION
Attach counters point are a family of APIs to attach individual counter
description definition to a verb object at a specific index location.
.PP
Counters object will start collecting values after it is bound to the
verb object resource.
.PP
A static attach can be created when NULL is provided instead of the
reference to the verbs object (e.g.: in case of flow providing NULL
instead of \f[I]flow\f[R]).
In this case, this counters object will only start collecting values
after it is bound to the verbs resource, for flow this is when
referencing the counters handle when creating a flow with
\f[B]ibv_create_flow\f[R]().
.PP
Once an ibv_counters is bound statically to a verbs resource, no
additional attach is allowed till the counter object is not bound to any
verb object.
.PP
The argument counter_desc specifies which counter value should be
collected.
It is defined in verbs.h as one of the enum ibv_counter_description
options.
.PP
Supported capabilities of specific counter_desc values per verbs object
can be tested by checking the return value for success or ENOTSUP errno.
.PP
Attaching a counters handle to multiple objects of the same type will
accumulate the values into a single index.
e.g.: creating several ibv_flow(s) with the same ibv_counters handle
will collect the values from all relevant flows into the relevant index
location when reading the values from \f[B]ibv_read_counters\f[R](),
setting the index more than once with different or same counter_desc
will aggregate the values from all relevant counters into the relevant
index location.
.PP
The runtime values of counters can be read from the hardware by calling
\f[B]ibv_read_counters\f[R]().
.SH ARGUMENTS
.TP
\f[I]counters\f[R]
Existing counters to attach new counter point on.
.TP
\f[I]counter_attach_attr\f[R]
An ibv_counter_attach_attr struct, as defined in verbs.h.
.TP
\f[I]flow\f[R]
Existing flow to attach a new counters point on (in static mode it must
be NULL).
.SS \f[I]counter_attach_attr\f[R] Argument
.IP
.EX
struct ibv_counter_attach_attr {
    enum ibv_counter_description counter_desc;
    uint32_t index;
    uint32_t comp_mask;
};
.EE
.SS \f[I]counter_desc\f[R] Argument
.IP
.EX
enum ibv_counter_description {
    IBV_COUNTER_PACKETS,
    IBV_COUNTER_BYTES,
};
.EE
.TP
\f[I]index\f[R]
Desired location of the specific counter at the counters object.
.TP
\f[I]comp_mask\f[R]
Bitmask specifying what fields in the structure are valid.
.SH RETURN VALUE
\f[B]ibv_attach_counters_point_flow\f[R]() returns 0 on success, or the
value of errno on failure (which indicates the failure reason)
.SH ERRORS
.TP
EINVAL
invalid argument(s) passed
.TP
ENOTSUP
\f[I]counter_desc\f[R] is not supported on the requested object
.TP
EBUSY
the counter object is already bound to a flow, additional attach calls
is not allowed (valid for static attach only)
.TP
ENOMEM
not enough memory
.SH NOTES
Counter values in each index location are cleared upon creation when
calling \f[B]ibv_create_counters\f[R]().
Attaching counters points will only increase these values accordingly.
.SH EXAMPLE
An example of use of \f[B]ibv_attach_counters_point_flow\f[R]() is shown
in \f[B]ibv_read_counters\f[R]
.SH SEE ALSO
\f[B]ibv_create_counters\f[R], \f[B]ibv_destroy_counters\f[R],
\f[B]ibv_read_counters\f[R], \f[B]ibv_create_flow\f[R]
.SH AUTHORS
Raed Salem \c
.MT raeds@mellanox.com
.ME \c
.PP
Alex Rosenbaum \c
.MT alexr@mellanox.com
.ME \c
