.TH LIBCOOPGAMMA_SET_GAMMA_SEND 3 LIBCOOPGAMMA
.SH "NAME"
libcoopgamma_set_gamma_send - Send a request to add, update, or remove a gamma ramp filter for CRTC
.SH "SYNOPSIS"
.nf
#include <libcoopgamma.h>

int libcoopgamma_set_gamma_send(const libcoopgamma_filter_t *restrict \fIfilter\fP,
                                libcoopgamma_context_t *restrict \fIctx\fP,
                                libcoopgamma_async_context_t *restrict \fIasync\fP);
.fi
.P
Link with
.IR -lcoopgamma .
.SH "DESCRIPTION"
The
.BR libcoopgamma_set_gamma_send ()
function sends a request over the connection of
.I ctx
to add, update, or remove a gamma ramp filter for
the CRTC with the name given in
.IR filter->crtc .
Information about the request is stored in
.IR *async ,
this information is used by
.BR libcoopgamma_synchronise (3)
to identify the response, and by
.BR libcoopgamma_get_gamma_recv (3)
to parse the response.
.P
A filter with the class (identifier)
.I filter->class
is removed if
.I filter->lifespan
is
.IR LIBCOOPGAMMA_REMOVE .
If
.I filter->lifespan
is not
.IR LIBCOOPGAMMA_REMOVE ,
a filter with matching class is updated
if such filter exists, otherwise the filter is
added. The fitler, unless it is removed, is
inserted or moved to the priority specified by
.IR filter->priority .
.I filter->priority
is isregarded when
.I filter->lifespan
is
.IR LIBCOOPGAMMA_REMOVE .
A filter with high priority is applied before
a fitler with low priority. The filter is removed
when it is explicit removed used
.IR LIBCOOPGAMMA_REMOVE ,
or if
.I filter->lifespan
is
.IR LIBCOOPGAMMA_UNTIL_DEATH ,
when the client that last added or updated
the filter disconnects from the server, which
ever comes first. Note that, when updating a
filter, the lifespan is updated to
.IR filter->lifespan .
.P
The class
.RI ( filter->class )
must be of the format
\fI${PACKAGE_NAME}\fP\fB::\fP\fI${COMMAND_NAME}\fP\fB::\fP\fI${RULE}\fP,
where
.I ${PACKAGE_NAME}
is the name of the package as installed on the system,
the program should make it easy to adjust this;
.I ${COMMAND_NAME}
is the name of the program, this too should not
easily adjustable, and
.I ${RULE}
is a string that identifies filter uniquely within
the program, or can be hardcoded or runtime
configurable.
.P
Unless
.I filter->lifespan
is
.IR LIBCOOPGAMMA_REMOVE ,
.I filter->depth
and
.I filter->ramps
must be configured to specified the desired ramp values.
.SH "RETURN VALUES"
Upon successful completion, the
.BR libcoopgamma_set_gamma_send ()
function returns 0. On error, -1 is returned and
.I errno
is set appropriately.
.SH "ERRORS"
The
.BR libcoopgamma_set_gamma_send ()
function may fail for any reason specified for
.BR malloc (3),
.BR realloc (3),
or
.BR libcoopgamma_flush (3).
Particularly interesting exceptional
conditions, that are not errors proper, include
those indicated by the following values on
.IR errno :
.TP
.B EINTR
The function was interrupted by a signal. When
this happens, call
.BR libcoopgamma_flush (3)
to resume.
.TP
.BR EAGAIN " or " EWOULDBLOCK
The communication is nonblocking and the buffer
between the server and the client is full,
and no more data can be queued without blocking.
When this happens, wait a short period of time
and call
.BR libcoopgamma_flush (3)
to resume.
.BR select (3)
or similar function can be used to wait until
.I ctx->fd
is readable.
.TP
.B ECONNREST
The connection to the server has closed.
.SH "SEE ALSO"
.BR libcoopgamma.h (0),
.BR libcoopgamma_filter_initialise (3),
.BR libcoopgamma_async_context_initialise (3),
.BR libcoopgamma_flush (3),
.BR libcoopgamma_synchronise (3),
.BR libcoopgamma_set_nonblocking (3),
.BR libcoopgamma_set_gamma_recv (3),
.BR libcoopgamma_set_gamma_sync (3),
.BR libcoopgamma_get_crtcs_send (3),
.BR libcoopgamma_get_gamma_send (3),
.BR libcoopgamma_set_gamma_send (3)