ctlseqs/man/ctlseqs_reader_config.3

98 lines
2.0 KiB
Groff

.TH CTLSEQS_READER_CONFIG 3 "Sep 01, 2020" 0.1.0 ctlseqs
.
.SH NAME
ctlseqs_reader_config - configure control sequence reader
.
.SH SYNOPSYS
.nf
.B #include <ctlseqs.h>
.PP
.B int ctlseqs_reader_config(
.BI " struct ctlseqs_reader *" reader ,
.BI " struct ctlseqs_reader_options const *" options
.B );
.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
.B 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 Supported flags
.TP
.B CTLSEQS_READER_NO_POLL
In a
.B ctlseqs_read
call, do not
.B poll
before
.BR read .
You may want this option enabled if
.I fd
is polled elsewhere (e.g. 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
.I result
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,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_read (3)