diff options
Diffstat (limited to 'man/man3/rpmatch.3')
| -rw-r--r-- | man/man3/rpmatch.3 | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/man/man3/rpmatch.3 b/man/man3/rpmatch.3 new file mode 100644 index 000000000..fd285cc64 --- /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 (date) "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) |