.TH CTLSEQS_READ 3 "Sep 01, 2020" 0.1.0 ctlseqs
.
.SH NAME
ctlseqs_read - read control sequence
.
.SH SYNOPSYS
.nf
.B #include <ctlseqs.h>
.PP
.B ssize_t ctlseqs_read(
.BI "    struct ctlseqs_reader        *" reader ,
.BI "    struct ctlseqs_matcher const *" matcher ,
.BI "    int                           " timeout
.B );
.fi
.
.SH DESCRIPTION
Attempts to read a control sequence with given
.IR reader ,
and match it against the patterns in
.IR matcher ,
similar to
.BR ctlseqs_match .
.PP
When match fails, the number of characters read will be stored into the
.I result
field in
.I reader
at offset 0, and the pointer to the first character stored at offset 1.
If option
.B CTLSEQS_READER_SAVE_MATCHED_SEQS
is enabled, also save those values when the match is successful.
.PP
Argument
.I timeout
is the maximum duration of time (in milliseconds) to wait until any data can be
read.
If
.I timeout
is -1, the function blocks indefinitely. If option
.B CTLSEQS_READER_NO_POLL
is enabled, this argument has no effect.
.SS Match results
For a successful match, the extracted values are stored in
.I result
like
.BR ctlseqs_match ,
but starting at offset 0 unless
.B CTLSEQS_READER_SAVE_MATCHED_SEQS
is enabled.
.
.SH RETURN VALUE
If a control sequence is successfully read, and matches at least one pattern in
.IR matcher ,
returns a non-negative integer representing the offset of a matching pattern.
.PP
Otherwise, returns a negative value:
.TP
.B CTLSEQS_NOMATCH
A control sequence is successfully read, but fails to match any pattern in
.IR matcher .
.TP
.B CTLSEQS_PARTIAL
Data is read successfully and can be recognized as part of a control sequence,
but is not yet terminated.  Partial sequence is not consumed from the read
buffer.
.TP
.B CTLSEQS_NOSEQ
Data is read successfully, but cannot be recognized as a valid control
sequence.
.TP
.B CTLSEQS_TIMEOUT
The specified
.I timeout
has expired, and no data is read.
.TP
.B CTLSEQS_NOMEM
Like
.BR CTLSEQS_PARTIAL ,
but the internal read buffer is full, and no data can be further read.
.TP
.B CTLSEQS_EOF
End-of-file is encountered, and no data is read.
.TP
.B CTLSEQS_ERROR
An unexpected error occurs during a system call within the function.
.TP
.B CTLSEQS_INTR
A system call within the function is interrupted by a signal, and no data is
read.
.
.SH COPYRIGHT
Copyright (c)  2020,2021  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_match (3),
.BR ctlseqs_matcher_config (3),
.BR ctlseqs_reader_config (3)