ctlseqs/man/ctlseqs_reader_config.3

.TH CTLSEQS_READER_CONFIG 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
.
.SH NAME
ctlseqs_reader_config - configure control sequence reader
.
.SH SYNOPSYS
.nf
.B #include <ctlseqs.h>
.PP
.BI "int ctlseqs_reader_config(struct ctlseqs_reader *" reader ,
.BI "    struct ctlseqs_reader_options const *" options );
.fi
.
.SH DESCRIPTION
Changes the properties of the given
.IR reader .
.PP
The
.I options
argument is a pointer to a
.BR "struct ctlseqs_reader_options" ,
as shown below:
.PP
.nf
.in +4n
.EX
struct ctlseqs_reader_options {
    union ctlseqs_value *result;
    size_t               maxlen;
    int                  fd;
    unsigned             flags;
};
.EE
.in
.fi
.PP
Field
.I result
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 Extracted values
An extracted value can be either a string (not guaranteed to be NUL-terminated), or an unsigned integer, as in
.BR "union ctlseqs_value" :
.PP
.nf
.in +4n
.EX
union ctlseqs_value {
    char const    *str;
    unsigned long  num;
};
.EE
.in
.fi
.PP
Once a sequence is successfully matched, a group of values is extracted from the sequence for each placeholder, and stored into
.I result
sequentially.
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 ,
.BR CTLSEQS_NOMATCH ,
.B CTLSEQS_PARTIAL
or
.BR CTLSEQS_NOMEM ,
the length of the entire string followed by the string itself will be stored into
.IR result .
The same is true for a successful match when option
.B CTLSEQS_READER_SAVE_MATCHED_SEQS
is enabled, inserting these two values before the extracted ones.
.SS Flags
Flags are boolean switches which can be combined as a bitmask for the
.I flags
option.
.PP
Currently supported 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_SAVE_MATCHED_SEQS
When a sequence is successfully matched against a pattern during
.BR ctlseqs_read (),
save the original sequence to buffer alongside the extracted values.
.
.SH RETURN VALUE
.TP
.B CTLSEQS_OK
Success.
.TP
.B CTLSEQS_NOMEM
Fails to allocate sufficient memory.
.TP
.B CTLSEQS_ERROR
Attempts to change
.I maxlen
value, but data in the internal read buffer will be lost due to truncation, if done so.
.
.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.
.
.SH SEE ALSO
.BR ctlseqs_read (3)