100 lines
2.9 KiB
Groff
100 lines
2.9 KiB
Groff
.TH CTLSEQS_READ 3 "Sep 01, 2020" 0.1.0 "Ctlseqs Library Manual"
|
|
.
|
|
.SH NAME
|
|
ctlseqs_read - read control sequence
|
|
.
|
|
.SH SYNOPSYS
|
|
.nf
|
|
.B #include <ctlseqs.h>
|
|
.PP
|
|
.BI "ssize_t ctlseqs_read(struct ctlseqs_reader *" reader ,
|
|
.BI " struct ctlseqs_matcher const *" matcher ", int " timeout );
|
|
.fi
|
|
.
|
|
.SH DESCRIPTION
|
|
Attempts to read a terminal control sequence, and extract values according to given patterns.
|
|
.PP
|
|
The
|
|
.I reader
|
|
argument specifies the behaviour of the read operation, which can be configured with
|
|
.BR ctlseqs_reader_setopt ().
|
|
.PP
|
|
The
|
|
.I matcher
|
|
argument specifies the expected patterns of control sequences to be matched upon after a successful read, which can be configured with
|
|
.BR ctlseqs_matcher_setopt ().
|
|
A NULL
|
|
.I matcher
|
|
is allowed, acting as if
|
|
.I npatterns
|
|
is 0.
|
|
.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.
|
|
.
|
|
.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 one of the matching patterns.
|
|
.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.
|
|
.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_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 NOTES
|
|
Any pattern in
|
|
.I matcher
|
|
must be a ECMA-35/ECMA-48 conformant escape sequence, and should also be recognizable by the matcher.
|
|
Otherwise, function behaviour is undefined.
|
|
.PP
|
|
Currently supported escape sequences:
|
|
.TP
|
|
.B CSI [param...] [intmd...] final
|
|
Parameter bytes are of range 0x30\(ti0x3f, intermediate bytes 0x20\(ti0x2f, and final byte 0x40\(ti0x7e.
|
|
.TP
|
|
.B (APC|DCS|OSC|PM) [cmdstr] ST
|
|
Command string consists of bytes of printable characters and characters of range 0x08\(ti0x0d.
|
|
.TP
|
|
.B (SS2|SS3) ch
|
|
The byte following a single-shift should be a printable character.
|
|
.TP
|
|
.B SOS [chrstr] ST
|
|
Character string can be any bit combination which does not represent SOS or ST.
|
|
.SH SEE ALSO
|
|
.BR ctlseqs_matcher_setopt (3),
|
|
.BR ctlseqs_reader_setopt (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.
|