155 lines
3.9 KiB
Groff
155 lines
3.9 KiB
Groff
.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.
|