.TH CTLSEQS_READER_SETOPT 3 "Sep 01, 2020" 0.1.0 "Ctlseqs Library Manual"
.
.SH NAME
ctlseqs_reader_setopt - set control sequence reader options
.
.SH SYNOPSYS
.nf
.B #include <ctlseqs.h>
.PP
.BI "int ctlseqs_reader_setopt(struct ctlseqs_reader *" reader ,
.BI "    struct ctlseqs_reader_opts const *" options );
.fi
.
.SH DESCRIPTION
Function
.BR ctlseqs_reader_setopt ()
changes the properties of the given
.IR reader .
.PP
The
.I options
argument is a pointer to a
.BR "struct ctlseqs_reader_opts" ,
as shown below:
.PP
.nf
.in +4n
.EX
struct ctlseqs_reader_opts {
    union ctlseqs_value *buffer;
    size_t               maxlen;
    int                  fd;
    unsigned             flags;
};
.EE
.in
.fi
.PP
Field
.I buffer
is the pointer to the buffer where the values extracted from the matching sequence of
.BR ctlseqs_read ()
will be stored.
.PP
Field
.I maxlen
specifies the maximum possible length (in bytes) of control sequence to be read.
.PP
Field
.I fd
is the file descriptor to read from.
.PP
Field
.I flags
is the bit mask of multiple boolean options.
.SS Buffer Values
A
.I buffer
is an array of
.BR "union ctlseqs_value" ,
as shown below:
.PP
.nf
.in +4n
.EX
union ctlseqs_value {
    char const    *str;
    unsigned long  num;
};
.EE
.in
.fi
.PP
The value can be either a string (not guaranteed to be NUL-terminated), or an unsigned integer.
Once a sequence is successfully matched, a group of values is extracted from the sequence for each placeholder, and stored into the buffer sequentially.
.PP
A group can contain one or multiple values, depending on different placeholders:
.TP
.B CTLSEQS_PH_NUM
A single unsigned integer.
.TP
.B CTLSEQS_PH_NUMS
An unsigned integer indicating the number of extracted values, followed by unsigned integers of that many.
.TP
.B CTLSEQS_PH_STR
An unsigned integer indicating the number of characters of the extracted string, followed by a string of printable characters.
.TP
.B CTLSEQS_PH_CMDSTR
An unsigned integer indicating the number of characters of the extracted string, followed by a string containing only printable characters and characters of range 0x08\(ti0x0d.
.TP
.B CTLSEQS_PH_CSI_PARAM
An unsigned integer indicating the number of characters of the extracted string, followed by a string of CSI parameter bytes (range 0x30\(ti0x3f).
.TP
.B CTLSEQS_PH_CSI_INTMD
An unsigned integer indicating the number of characters of the extracted string, followed by a string of CSI intermediate bytes (range 0x20\(ti0x2f).
.TP
.B CTLSEQS_PH_HEXNUM
A single unsigned integer, which is the integer value of extracted hexadecimal string.
.TP
.B CTLSEQS_PH_CHRSTR
An unsigned integer indicating the number of characters of the extracted string, followed by a string of any bit combination which does not represent SOS or ST.
.PP
If the
.BR ctlseqs_read ()
call returns
.BR CTLSEQS_NOSEQ ,
.B CTLSEQS_NOMATCH
or
.BR CTLSEQS_PARTIAL ,
the length of the entire string followed by the string itself will be stored into the buffer.
.SS Flags
.TP
.B CTLSEQS_READER_NO_POLL
In a
.BR ctlseqs_read ()
call, do not
.BR poll ()
before
.BR read ().
You may want this option enabled if
.I fd
is maintained in an event loop.
.TP
.B CTLSEQS_READER_RETAIN_PARTIAL
When
.BR ctlseqs_read ()
returns
.BR CTLSEQS_PARTIAL ,
preserve the partially matched sequence in the internal buffer for future calls.
.
.SH RETURN VALUE
.TP
.B CTLSEQS_OK
Success.
.TP
.B CTLSEQS_NOMEM
Fails to allocate sufficient memory.
.SH BUGS
After a successful
.BR ctlseqs_read ()
call, changing
.I maxlen
to a smaller value on the same
.I reader
may result in data loss due to truncation of the internal read buffer.
.
.SH SEE ALSO
.BR ctlseqs_read (3)
.
.SH COPYRIGHT
Copyright (c)  2020  CismonX <admin@cismon.net>
.PP
Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
This file is offered as-is, without any warranty.