Update documentation.
continuous-integration/drone/push Build is failing
Details
continuous-integration/drone/push Build is failing
Details
This commit is contained in:
parent
471825b0ac
commit
da11b51814
167
doc/ctlseqs.texi
167
doc/ctlseqs.texi
|
@ -43,13 +43,13 @@ license is included in the section entitled ``GNU Free Documentation License''.
|
|||
|
||||
This manual is for ctlseqs, a helper library for control sequences.
|
||||
|
||||
Permission is granted to copy, distribute and/or modify this document under the
|
||||
terms of the @pxref{GNU Free Documentation License}, Version 1.3 or any later
|
||||
version published by the Free Software Foundation; with no Invariant Sections,
|
||||
with no Front-Cover Texts, and with no Back-Cover Texts.
|
||||
Permission is granted to copy, distribute and/or modify this document under
|
||||
the terms of the @pxref{GNU Free Documentation License}, Version 1.3 or
|
||||
any later version published by the Free Software Foundation; with no
|
||||
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.
|
||||
|
||||
ctlseqs is free software. You can redistribute it and/or modify it under the
|
||||
terms of the GNU General Public License as published by the Free Software
|
||||
ctlseqs is free software. You can redistribute it and/or modify it under
|
||||
the terms of the GNU General Public License as published by the Free Software
|
||||
Foundation, either version 3 of the License, or (at your option) any later
|
||||
version.
|
||||
@end ifnottex
|
||||
|
@ -93,33 +93,14 @@ them can be used separatedly or combined, after including the header file
|
|||
@node Contributing
|
||||
@section Contributing
|
||||
|
||||
@set ctlseqs-repo-url https://savannah.nongnu.org/projects/ctlseqs
|
||||
|
||||
We welcome any form of contribution to ctlseqs (as well as this manual),
|
||||
including bug reports, patches, etc.
|
||||
|
||||
As ctlseqs is primarily @url{https://sv.gnu.org/p/ctlseqs, hosted on Savannah},
|
||||
it is recommended to contribute using the bug tracker and patch manager.
|
||||
Sending an email to @email{bug-report@@cismon.net} is also a viable option.
|
||||
|
||||
@cindex Checklist for bug reports
|
||||
An effective bug report should contain enough information to reproduce the bug,
|
||||
which may contain:
|
||||
|
||||
@itemize @bullet
|
||||
@item The version number of ctlseqs involved.
|
||||
@item A minimal code snippet to reproduce the bug.
|
||||
@item Expected and actual behaviour of the program.
|
||||
@item A core file for the crashed program.
|
||||
@item Name of the operating system and hardware.
|
||||
@end itemize
|
||||
|
||||
@cindex Checklist for patch submission
|
||||
Before you submit a patch for ctlseqs, it is recommended to:
|
||||
|
||||
@itemize @bullet
|
||||
@item Follow the existing coding style.
|
||||
@item Discuss with the community about new features or breaking changes.
|
||||
@item Write test cases, documentation and changelogs for your code.
|
||||
@end itemize
|
||||
Source code of ctlseqs is @url{@value{ctlseqs-repo-url}, hosted on Savannah}.
|
||||
You can contribute to ctlseqs using the bug tracker and patch manager,
|
||||
or discuss with the community using the mailing lists.
|
||||
|
||||
|
||||
@node Use Scenarios
|
||||
|
@ -132,15 +113,15 @@ embedded in normal text. Such physical terminals are no longer used today,
|
|||
however, popular ones like DEC VT100 are widely emulated by modern terminal
|
||||
emulators.
|
||||
|
||||
The primary purpose of the ctlseqs library is to provide developers with a set
|
||||
of simple and easy-to-use API for handling control functions, when working on
|
||||
The primary purpose of the ctlseqs library is to provide developers with
|
||||
simple and easy-to-use API for handling control functions, when working on
|
||||
terminal emulators and text-based programs.
|
||||
|
||||
However, while there is no de facto standard, control functions used in
|
||||
However, since there is no de facto standard, control functions used in
|
||||
terminals are largely vendor-specific, and terminal emulators like to add their
|
||||
own private controls. That makes ctlseqs not suitable for writing text-based
|
||||
programs which intend to be portable. Instead of raw control codes, the
|
||||
developer should stick to ncurses or terminfo.
|
||||
programs which intend to be portable. Instead of raw control codes, developers
|
||||
should stick to ncurses or terminfo.
|
||||
|
||||
@cindex List of common use cases of ctlseqs
|
||||
There are still cases when dealing with raw escape sequences is inevitable, and
|
||||
|
@ -158,8 +139,8 @@ terminal emulators.
|
|||
@node Helper Macros
|
||||
@chapter Helper Macros
|
||||
|
||||
A helper macro in ctlseqs is a C preprocessor macro representing a control
|
||||
function, which expands to a C string literal.
|
||||
ctlseqs provides C preprocessor macros representing control functions, which
|
||||
expand to C string literals.
|
||||
|
||||
@cindex List of control function types in ctlseqs helper macros
|
||||
The control function can be one of the following three types:
|
||||
|
@ -170,12 +151,12 @@ The control function can be one of the following three types:
|
|||
@item Other control functions (such as device control functions).
|
||||
@end itemize
|
||||
|
||||
Name of a helper macro is the function name with @code{CTLSEQS_} as prefix.
|
||||
For a control function other than elements from the C0 or C1 set, the
|
||||
corresponding helper macro is a function-like macro which may or may not take
|
||||
arguments.
|
||||
The name of a helper macro is the control function name with @code{CTLSEQS_}
|
||||
as prefix. For a control function other than elements from the C0 or C1 set,
|
||||
the corresponding helper macro is a function-like macro which may or may not
|
||||
take arguments.
|
||||
|
||||
Control sequences listed in the helper macros are primarily exerpted from
|
||||
Control sequences listed in the helper macros are primarily excerpted from
|
||||
@url{https://invisible-island.net/xterm/ctlseqs/ctlseqs.html, XTerm's manual},
|
||||
which may differ across implementations.
|
||||
|
||||
|
@ -232,8 +213,8 @@ ctlseqs_matcher_free(matcher);
|
|||
@end example
|
||||
|
||||
On rare occurences when ctlseqs fail to allocate enough memory, function
|
||||
@code{ctlseqs_matcher_init} may return @code{NULL}. However, it is okay to pass
|
||||
null pointers to @code{ctlseqs_matcher_free}, which in turn does nothing.
|
||||
@code{ctlseqs_matcher_init} may return @code{NULL}.
|
||||
However, it is safe to pass null pointers to @code{ctlseqs_matcher_free}.
|
||||
|
||||
@menu
|
||||
* Matcher Configuration:: Configuring a control sequence matcher
|
||||
|
@ -245,8 +226,8 @@ null pointers to @code{ctlseqs_matcher_free}, which in turn does nothing.
|
|||
@section Matcher Configuration
|
||||
|
||||
Matcher configuration consists of two parts: the number of matching patterns,
|
||||
and the patterns themselves. Invoke function @code{ctlseqs_matcher_config} to
|
||||
configure a matcher.
|
||||
and the pattern values.
|
||||
Invoke function @code{ctlseqs_matcher_config} to configure a matcher.
|
||||
|
||||
@cindex Control sequence matcher configuration example
|
||||
@example
|
||||
|
@ -262,10 +243,10 @@ int result = ctlseqs_matcher_config(matcher, &options);
|
|||
// ...
|
||||
@end example
|
||||
|
||||
Each invocation of @code{ctlseqs_matcher_config} on the same matcher overwrites
|
||||
the data generated from the last invocation. Upon success, the function returns
|
||||
@code{CTLSEQS_OK}. If the function fails to allocate enough memory, returns
|
||||
@code{CTLSEQS_NOMEM}.
|
||||
Each invocation of @code{ctlseqs_matcher_config} on the same matcher
|
||||
overwrites the data generated from the last invocation.
|
||||
Upon success, the function returns @code{CTLSEQS_OK}.
|
||||
If the function fails to allocate enough memory, returns @code{CTLSEQS_NOMEM}.
|
||||
|
||||
@quotation Caution
|
||||
If the @code{patterns} field in @code{struct ctlseqs_matcher_options} is
|
||||
|
@ -296,19 +277,21 @@ The following types of control functions are recognizable by the matcher:
|
|||
|
||||
According to ECMA-48, CSI parameter bytes are of range @code{0x30} to
|
||||
@code{0x3f}, intermediate bytes @code{0x20} to @code{0x2f}, and final byte
|
||||
@code{0x40} to @code{0x7e}. Command string consists of printable characters and
|
||||
characters of range @code{0x08} and @code{0x0e}. Character string can be any
|
||||
bit combination which does not represent @code{SOS} or @code{ST}.
|
||||
@code{0x40} to @code{0x7e}.
|
||||
Command string consists of printable characters and characters of range
|
||||
@code{0x08} and @code{0x0e}.
|
||||
Character string can be any bit combination which does not represent
|
||||
@code{SOS} or @code{ST}.
|
||||
|
||||
A supported control function, either verbatim or combined with placeholders,
|
||||
can be specified as a valid pattern. The terminating @code{NUL} character does
|
||||
not count into the pattern.
|
||||
can be specified as a valid pattern.
|
||||
The terminating @code{NUL} character does not count into the pattern.
|
||||
|
||||
@cindex List of supported placeholders
|
||||
A placeholder indicates that when matching a string against the pattern, the
|
||||
value at the placeholder's location should conform to its rules. A placeholder
|
||||
can only take place in the @code{param}, @code{intmd}, @code{cmdstr} or
|
||||
@code{chrstr} fields, and can be one of the following values:
|
||||
A placeholder indicates that when matching a string against the pattern,
|
||||
the value at the placeholder's location should conform to its rules.
|
||||
A placeholder can only take place in the @code{param}, @code{intmd},
|
||||
@code{cmdstr} or @code{chrstr} fields, and can be one of the following values:
|
||||
|
||||
@itemize @bullet
|
||||
@item @code{CTLSEQS_PH_NUM}: An unsigned integer.
|
||||
|
@ -363,8 +346,9 @@ offset 0, and the pointer to the first character of the control funtion at the
|
|||
@code{str} field at offset 1.
|
||||
|
||||
If @code{ctlseqs_match} fails to find any control functions, returns
|
||||
@code{CTLSEQS_NESEQ}. For a partial control function, returns
|
||||
@code{CTLSEQS_PARTIAL}. If the matcher is not configured with a pattern of the
|
||||
@code{CTLSEQS_NOSEQ}.
|
||||
For a partial control function, returns @code{CTLSEQS_PARTIAL}.
|
||||
If the matcher is not configured with a matching pattern of the
|
||||
control function, the function returns @code{CTLSEQS_NOMATCH}.
|
||||
|
||||
If the control function matches a pattern configured in the matcher, returns
|
||||
|
@ -403,7 +387,7 @@ patterns is provided.
|
|||
|
||||
@quotation Caution
|
||||
If the given string can match multiple patterns in the matcher, it is
|
||||
unspecified which of them will be the final match result.
|
||||
unspecified which one of them will be the final match result.
|
||||
@end quotation
|
||||
|
||||
|
||||
|
@ -418,81 +402,106 @@ unspecified which of them will be the final match result.
|
|||
@node Example Programs
|
||||
@chapter Example Programs
|
||||
|
||||
There are a few example programs which may shed some light on using ctlseqs.
|
||||
|
||||
@node API Reference
|
||||
@appendix API Reference
|
||||
|
||||
This appendix section contains a complete list of functions exposed by ctlseqs,
|
||||
which is meant for a TL;DR purpose. See the corresponding man(3) pages for
|
||||
concise details.
|
||||
This section contains a complete list of functions exposed by ctlseqs, which is
|
||||
meant for a TL;DR purpose. See the corresponding man(3) pages for details.
|
||||
|
||||
Initialize matcher:
|
||||
|
||||
@example
|
||||
struct ctlseqs_matcher *ctlseqs_matcher_init(void);
|
||||
struct ctlseqs_matcher *
|
||||
ctlseqs_matcher_init(void);
|
||||
@end example
|
||||
|
||||
Configure matcher:
|
||||
|
||||
@example
|
||||
int ctlseqs_matcher_config(
|
||||
int
|
||||
ctlseqs_matcher_config(
|
||||
struct ctlseqs_matcher *matcher,
|
||||
struct ctlseqs_matcher_options const *options);
|
||||
struct ctlseqs_matcher_options const *options
|
||||
);
|
||||
@end example
|
||||
|
||||
Match string:
|
||||
|
||||
@example
|
||||
ssize_t ctlseqs_match(
|
||||
ssize_t
|
||||
ctlseqs_match(
|
||||
struct ctlseqs_reader const *matcher,
|
||||
char const *str,
|
||||
size_t str_len,
|
||||
union ctlseqs_value *result);
|
||||
union ctlseqs_value *result
|
||||
);
|
||||
@end example
|
||||
|
||||
Destroy matcher:
|
||||
|
||||
@example
|
||||
void ctlseqs_matcher_free(struct ctlseqs_matcher *matcher);
|
||||
void
|
||||
ctlseqs_matcher_free(
|
||||
struct ctlseqs_matcher *matcher
|
||||
);
|
||||
@end example
|
||||
|
||||
Initialize reader:
|
||||
|
||||
@example
|
||||
struct ctlseqs_reader *ctlseqs_reader_init(void);
|
||||
struct ctlseqs_reader *
|
||||
ctlseqs_reader_init(void);
|
||||
@end example
|
||||
|
||||
Configure reader:
|
||||
|
||||
@example
|
||||
int ctlseqs_reader_config(
|
||||
int
|
||||
ctlseqs_reader_config(
|
||||
struct ctlseqs_reader *reader,
|
||||
struct ctlseqs_reader_options const *options);
|
||||
struct ctlseqs_reader_options const *options
|
||||
);
|
||||
@end example
|
||||
|
||||
Read and match:
|
||||
|
||||
@example
|
||||
ssize_t ctlseqs_read(
|
||||
ssize_t
|
||||
ctlseqs_read(
|
||||
struct ctlseqs_reader *reader,
|
||||
struct ctlseqs_matcher const *matcher,
|
||||
int timeout);
|
||||
int timeout
|
||||
);
|
||||
@end example
|
||||
|
||||
Purge reader:
|
||||
|
||||
@example
|
||||
void ctlseqs_purge(
|
||||
void
|
||||
ctlseqs_purge(
|
||||
struct ctlseqs_reader *reader,
|
||||
size_t nbytes);
|
||||
size_t nbytes
|
||||
);
|
||||
@end example
|
||||
|
||||
Destroy reader:
|
||||
|
||||
@example
|
||||
void ctlseqs_reader_free(struct ctlseqs_reader *reader);
|
||||
void
|
||||
ctlseqs_reader_free(
|
||||
struct ctlseqs_reader *reader
|
||||
);
|
||||
@end example
|
||||
|
||||
|
||||
@node Indices
|
||||
@appendix Indices
|
||||
|
||||
@printindex cp
|
||||
|
||||
|
||||
@node GNU Free Documentation License
|
||||
@appendix GNU Free Documentation License
|
||||
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
.TH CTLSEQS_MATCH 3 "Dec 23, 2020" 0.1.0 "ctlseqs Library Manual"
|
||||
.TH CTLSEQS_MATCH 3 "Dec 23, 2020" 0.1.0 ctlseqs
|
||||
.
|
||||
.SH NAME
|
||||
ctlseqs_match - match control sequence
|
||||
|
@ -7,8 +7,12 @@ ctlseqs_match - match control sequence
|
|||
.nf
|
||||
.B #include <ctlseqs.h>
|
||||
.PP
|
||||
.BI "ssize_t ctlseqs_match(struct ctlseqs_reader const *" matcher ,
|
||||
.BI " char const *" str ", size_t " str_len ", union ctlseqs_value *" result );
|
||||
.B ssize_t ctlseqs_match(
|
||||
.BI " struct ctlseqs_matcher const *" matcher ,
|
||||
.BI " char const *" str ,
|
||||
.BI " size_t " str_len ,
|
||||
.BI " union ctlseqs_value *" result
|
||||
.B );
|
||||
.fi
|
||||
.
|
||||
.SH DESCRIPTION
|
||||
|
@ -97,7 +101,7 @@ The string can be recognized as part of a control sequence, but is not yet termi
|
|||
No valid control sequence is found in the given string.
|
||||
.
|
||||
.SH COPYRIGHT
|
||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
||||
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.
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
.TH CTLSEQS_MATCHER_CONFIG 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
||||
.TH CTLSEQS_MATCHER_CONFIG 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||
.
|
||||
.SH NAME
|
||||
ctlseqs_matcher_config - configure control sequence matcher
|
||||
|
@ -7,8 +7,10 @@ ctlseqs_matcher_config - configure control sequence matcher
|
|||
.nf
|
||||
.B #include <ctlseqs.h>
|
||||
.PP
|
||||
.BI "int ctlseqs_matcher_config(struct ctlseqs_matcher *" matcher ,
|
||||
.BI " struct ctlseqs_matcher_options const *" options );
|
||||
.B int ctlseqs_matcher_config(
|
||||
.BI " struct ctlseqs_matcher *" matcher ,
|
||||
.BI " struct ctlseqs_matcher_options const *" options
|
||||
.B );
|
||||
.fi
|
||||
.
|
||||
.SH DESCRIPTION
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
.TH CTLSEQS_MATCHER_FREE 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
||||
.TH CTLSEQS_MATCHER_FREE 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||
.
|
||||
.SH NAME
|
||||
ctlseqs_matcher_free - free control sequence matcher
|
||||
|
@ -7,15 +7,17 @@ ctlseqs_matcher_free - free control sequence matcher
|
|||
.nf
|
||||
.B #include <ctlseqs.h>
|
||||
.PP
|
||||
.BI "void ctlseqs_matcher_free(struct ctlseqs_matcher *" matcher ");"
|
||||
.B void ctlseqs_matcher_free(
|
||||
.BI " struct ctlseqs_matcher *" matcher
|
||||
.B );
|
||||
.fi
|
||||
.
|
||||
.SH DESCRIPTION
|
||||
Destroys a
|
||||
.I matcher
|
||||
instance created by
|
||||
.BR ctlseqs_matcher_init ()
|
||||
and releases its holding memory.
|
||||
.B ctlseqs_matcher_init
|
||||
and releases its memory.
|
||||
.PP
|
||||
If
|
||||
.I matcher
|
||||
|
@ -25,7 +27,7 @@ is NULL, this function has no effect.
|
|||
This function has no return values.
|
||||
.
|
||||
.SH COPYRIGHT
|
||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
||||
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.
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
.TH CTLSEQS_MATCHER_INIT 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
||||
.TH CTLSEQS_MATCHER_INIT 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||
.
|
||||
.SH NAME
|
||||
ctlseqs_matcher_init - initialize control sequence matcher
|
||||
|
@ -12,10 +12,10 @@ ctlseqs_matcher_init - initialize control sequence matcher
|
|||
.
|
||||
.SH DESCRIPTION
|
||||
Creates a control sequence matcher, which can be configured with
|
||||
.BR ctlseqs_matcher_config ().
|
||||
.BR ctlseqs_matcher_config .
|
||||
.PP
|
||||
Instance of a control sequence matcher should be freed with
|
||||
.BR ctlseqs_matcher_free ().
|
||||
Instance of a matcher should be freed with
|
||||
.BR ctlseqs_matcher_free .
|
||||
.
|
||||
.SH RETURN VALUE
|
||||
Returns a pointer to opaque type
|
||||
|
@ -25,7 +25,7 @@ holding the matcher instance.
|
|||
If the function fails to allocate sufficient memory, returns NULL.
|
||||
.
|
||||
.SH COPYRIGHT
|
||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
||||
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.
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
.TH CTLSEQS_PURGE 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
||||
.TH CTLSEQS_PURGE 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||
.
|
||||
.SH NAME
|
||||
ctlseqs_purge - purge read buffer
|
||||
|
@ -7,7 +7,10 @@ ctlseqs_purge - purge read buffer
|
|||
.nf
|
||||
.B #include <ctlseqs.h>
|
||||
.PP
|
||||
.BI "void ctlseqs_purge(struct ctlseqs_reader *" reader ", size_t " nbytes );
|
||||
.B void ctlseqs_purge(
|
||||
.BI " struct ctlseqs_reader *" reader ,
|
||||
.BI " size_t " nbytes
|
||||
.B );
|
||||
.fi
|
||||
.
|
||||
.SH DESCRIPTION
|
||||
|
@ -26,7 +29,7 @@ This function has no return values.
|
|||
.
|
||||
.SH NOTES
|
||||
The function is useful when dealing with partial sequences returned by
|
||||
.BR ctlseqs_read (),
|
||||
.BR ctlseqs_read ,
|
||||
whose future completion is not desired.
|
||||
.
|
||||
.SH COPYRIGHT
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
.TH CTLSEQS_READ 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
||||
.TH CTLSEQS_READ 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||
.
|
||||
.SH NAME
|
||||
ctlseqs_read - read control sequence
|
||||
|
@ -7,8 +7,11 @@ ctlseqs_read - read control sequence
|
|||
.nf
|
||||
.B #include <ctlseqs.h>
|
||||
.PP
|
||||
.BI "ssize_t ctlseqs_read(struct ctlseqs_reader *" reader ,
|
||||
.BI " struct ctlseqs_matcher const *" matcher ", int " timeout );
|
||||
.B ssize_t ctlseqs_read(
|
||||
.BI " struct ctlseqs_reader *" reader ,
|
||||
.BI " struct ctlseqs_matcher const *" matcher ,
|
||||
.BI " int " timeout
|
||||
.B );
|
||||
.fi
|
||||
.
|
||||
.SH DESCRIPTION
|
||||
|
@ -17,7 +20,7 @@ Attempts to read a control sequence with given
|
|||
and match it against the patterns in
|
||||
.IR matcher ,
|
||||
similar to
|
||||
.BR ctlseqs_match() .
|
||||
.BR ctlseqs_match .
|
||||
.PP
|
||||
When match fails, the number of characters read will be stored into the
|
||||
.I result
|
||||
|
@ -40,7 +43,7 @@ is enabled, this argument has no effect.
|
|||
For a successful match, the extracted values are stored in
|
||||
.I result
|
||||
like
|
||||
.BR ctlseqs_match() ,
|
||||
.BR ctlseqs_match ,
|
||||
but starting at offset 0 unless
|
||||
.B CTLSEQS_READER_SAVE_MATCHED_SEQS
|
||||
is enabled.
|
||||
|
@ -83,7 +86,7 @@ An unexpected error occurs during a system call within the function.
|
|||
A system call within the function is interrupted by a signal, and no data is read.
|
||||
.
|
||||
.SH COPYRIGHT
|
||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
||||
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.
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
.TH CTLSEQS_READER_CONFIG 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
||||
.TH CTLSEQS_READER_CONFIG 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||
.
|
||||
.SH NAME
|
||||
ctlseqs_reader_config - configure control sequence reader
|
||||
|
@ -7,8 +7,10 @@ ctlseqs_reader_config - configure control sequence reader
|
|||
.nf
|
||||
.B #include <ctlseqs.h>
|
||||
.PP
|
||||
.BI "int ctlseqs_reader_config(struct ctlseqs_reader *" reader ,
|
||||
.BI " struct ctlseqs_reader_options const *" options );
|
||||
.B int ctlseqs_reader_config(
|
||||
.BI " struct ctlseqs_reader *" reader ,
|
||||
.BI " struct ctlseqs_reader_options const *" options
|
||||
.B );
|
||||
.fi
|
||||
.
|
||||
.SH DESCRIPTION
|
||||
|
@ -37,7 +39,7 @@ struct ctlseqs_reader_options {
|
|||
Field
|
||||
.I result
|
||||
is the pointer to the buffer where the values extracted from the matching sequence of
|
||||
.BR ctlseqs_read ()
|
||||
.B ctlseqs_read
|
||||
will be stored.
|
||||
.PP
|
||||
Field
|
||||
|
@ -55,18 +57,18 @@ is the bit mask of multiple boolean options.
|
|||
.TP
|
||||
.B CTLSEQS_READER_NO_POLL
|
||||
In a
|
||||
.BR ctlseqs_read ()
|
||||
.B ctlseqs_read
|
||||
call, do not
|
||||
.BR poll ()
|
||||
.B poll
|
||||
before
|
||||
.BR read ().
|
||||
.BR read .
|
||||
You may want this option enabled if
|
||||
.I fd
|
||||
is maintained in an event loop.
|
||||
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 (),
|
||||
.BR ctlseqs_read ,
|
||||
save the original sequence to
|
||||
.I result
|
||||
alongside the extracted values.
|
||||
|
@ -85,7 +87,7 @@ Attempts to change
|
|||
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>
|
||||
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.
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
.TH CTLSEQS_MATCHER_FREE 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
||||
.TH CTLSEQS_MATCHER_FREE 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||
.
|
||||
.SH NAME
|
||||
ctlseqs_reader_free - free control sequence reader
|
||||
|
@ -7,14 +7,16 @@ ctlseqs_reader_free - free control sequence reader
|
|||
.nf
|
||||
.B #include <ctlseqs.h>
|
||||
.PP
|
||||
.BI "void ctlseqs_reader_free(struct ctlseqs_reader *" reader ");"
|
||||
.B void ctlseqs_reader_free(
|
||||
.BI " struct ctlseqs_reader *" reader
|
||||
.B );
|
||||
.fi
|
||||
.
|
||||
.SH DESCRIPTION
|
||||
Destroys a
|
||||
.I reader
|
||||
instance created by
|
||||
.BR ctlseqs_reader_init ()
|
||||
.B ctlseqs_reader_init
|
||||
and releases its holding memory.
|
||||
.PP
|
||||
If
|
||||
|
@ -25,7 +27,7 @@ is NULL, this function has no effect.
|
|||
This function has no return values.
|
||||
.
|
||||
.SH COPYRIGHT
|
||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
||||
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.
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
.TH CTLSEQS_READER_INIT 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
|
||||
.TH CTLSEQS_READER_INIT 3 "Sep 01, 2020" 0.1.0 ctlseqs
|
||||
.
|
||||
.SH NAME
|
||||
ctlseqs_reader_init - initialize control sequence reader
|
||||
|
@ -12,10 +12,10 @@ ctlseqs_reader_init - initialize control sequence reader
|
|||
.
|
||||
.SH DESCRIPTION
|
||||
Creates a control sequence reader, which can be configured with
|
||||
.BR ctlseqs_reader_config ().
|
||||
.BR ctlseqs_reader_config .
|
||||
.PP
|
||||
Instance of a control sequence reader should be freed with
|
||||
.BR ctlseqs_reader_free ().
|
||||
Instance of a reader should be freed with
|
||||
.BR ctlseqs_reader_free .
|
||||
.
|
||||
.SH RETURN VALUE
|
||||
Returns a pointer to opaque type
|
||||
|
@ -25,7 +25,7 @@ holding the reader instance.
|
|||
If the function fails to allocate sufficient memory, returns NULL.
|
||||
.
|
||||
.SH COPYRIGHT
|
||||
Copyright (c) 2020 CismonX <admin@cismon.net>
|
||||
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.
|
||||
|
|
Loading…
Reference in New Issue