summaryrefslogtreecommitdiffstats
path: root/man/man3/rpmatch.3
diff options
context:
space:
mode:
Diffstat (limited to 'man/man3/rpmatch.3')
-rw-r--r--man/man3/rpmatch.3169
1 files changed, 169 insertions, 0 deletions
diff --git a/man/man3/rpmatch.3 b/man/man3/rpmatch.3
new file mode 100644
index 0000000..5739b82
--- /dev/null
+++ b/man/man3/rpmatch.3
@@ -0,0 +1,169 @@
+'\" t
+.\" Copyright (C) 2006 Justin Pryzby <pryzbyj@justinpryzby.com>
+.\"
+.\" %%%LICENSE_START(PERMISSIVE_MISC)
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\"
+.\" The above copyright notice and this permission notice shall be
+.\" included in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+.\" %%%LICENSE_END
+.\"
+.\" References:
+.\" glibc manual and source
+.\"
+.\" 2006-05-19, mtk, various edits and example program
+.\"
+.TH rpmatch 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+rpmatch \- determine if the answer to a question is affirmative or negative
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.P
+.BI "int rpmatch(const char *" response );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR rpmatch ():
+.nf
+ Since glibc 2.19:
+ _DEFAULT_SOURCE
+ glibc 2.19 and earlier:
+ _SVID_SOURCE
+.fi
+.SH DESCRIPTION
+.BR rpmatch ()
+handles a user response to yes or no questions, with
+support for internationalization.
+.P
+.I response
+should be a null-terminated string containing a
+user-supplied response, perhaps obtained with
+.BR fgets (3)
+or
+.BR getline (3).
+.P
+The user's language preference is taken into account per the
+environment variables
+.BR LANG ,
+.BR LC_MESSAGES ,
+and
+.BR LC_ALL ,
+if the program has called
+.BR setlocale (3)
+to effect their changes.
+.P
+Regardless of the locale, responses matching
+.B \[ha][Yy]
+are always accepted as affirmative, and those matching
+.B \[ha][Nn]
+are always accepted as negative.
+.SH RETURN VALUE
+After examining
+.IR response ,
+.BR rpmatch ()
+returns 0 for a recognized negative response ("no"), 1
+for a recognized positive response ("yes"), and \-1 when the value
+of
+.I response
+is unrecognized.
+.SH ERRORS
+A return value of \-1 may indicate either an invalid input, or some
+other error.
+It is incorrect to only test if the return value is nonzero.
+.P
+.BR rpmatch ()
+can fail for any of the reasons that
+.BR regcomp (3)
+or
+.BR regexec (3)
+can fail; the cause of the error
+is not available from
+.I errno
+or anywhere else, but indicates a
+failure of the regex engine (but this case is indistinguishable from
+that of an unrecognized value of
+.IR response ).
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR rpmatch ()
+T} Thread safety MT-Safe locale
+.TE
+.SH STANDARDS
+None.
+.SH HISTORY
+GNU, FreeBSD, AIX.
+.SH BUGS
+The
+.BR YESEXPR " and " NOEXPR
+of some locales (including "C") only inspect the first character of the
+.IR response .
+This can mean that "yno" et al. resolve to
+.BR 1 .
+This is an unfortunate historical side-effect which should be fixed in time
+with proper localisation, and should not deter from
+.BR rpmatch ()
+being the proper way to distinguish between binary answers.
+.SH EXAMPLES
+The following program displays the results when
+.BR rpmatch ()
+is applied to the string given in the program's command-line argument.
+.P
+.\" SRC BEGIN (rpmatch.c)
+.EX
+#define _DEFAULT_SOURCE
+#include <locale.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+\&
+int
+main(int argc, char *argv[])
+{
+ if (argc != 2 || strcmp(argv[1], "\-\-help") == 0) {
+ fprintf(stderr, "%s response\en", argv[0]);
+ exit(EXIT_FAILURE);
+ }
+\&
+ setlocale(LC_ALL, "");
+ printf("rpmatch() returns: %d\en", rpmatch(argv[1]));
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR fgets (3),
+.BR getline (3),
+.BR nl_langinfo (3),
+.BR regcomp (3),
+.BR setlocale (3)