| .\" 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 2017-09-15 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| rpmatch \- determine if the answer to a question is affirmative or negative |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdlib.h> |
| .PP |
| .BI "int rpmatch(const char *" response ); |
| .fi |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR rpmatch (): |
| Since glibc 2.19: |
| _DEFAULT_SOURCE |
| Glibc 2.19 and earlier: |
| _SVID_SOURCE |
| .SH DESCRIPTION |
| .BR rpmatch () |
| handles a user response to yes or no questions, with |
| support for internationalization. |
| .PP |
| .I response |
| should be a null-terminated string containing a |
| user-supplied response, perhaps obtained with |
| .BR fgets (3) |
| or |
| .BR getline (3). |
| .PP |
| 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. |
| .PP |
| Regardless of the locale, responses matching |
| .B ^[Yy] |
| are always accepted as affirmative, and those matching |
| .B ^[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. |
| .PP |
| .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; |
| lb lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR rpmatch () |
| T} Thread safety MT-Safe locale |
| .TE |
| .sp 1 |
| .SH CONFORMING TO |
| .BR rpmatch () |
| is not required by any standard, but |
| is available on a few other systems. |
| .\" It is available on at least AIX 5.1 and FreeBSD 6.0. |
| .SH BUGS |
| The |
| .BR rpmatch () |
| implementation looks at only the first character |
| of |
| .IR response . |
| As a consequence, "nyes" returns 0, and |
| "ynever; not in a million years" returns 1. |
| It would be preferable to accept input strings much more |
| strictly, for example (using the extended regular |
| expression notation described in |
| .BR regex (7)): |
| .B ^([yY]|yes|YES)$ |
| and |
| .BR ^([nN]|no|NO)$ . |
| .SH EXAMPLE |
| The following program displays the results when |
| .BR rpmatch () |
| is applied to the string given in the program's command-line argument. |
| .PP |
| .EX |
| #define _SVID_SOURCE |
| #include <locale.h> |
| #include <stdlib.h> |
| #include <string.h> |
| #include <stdio.h> |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| if (argc != 2 || strcmp(argv[1], "\-\-help") == 0) { |
| fprintf(stderr, "%s response\\n", argv[0]); |
| exit(EXIT_FAILURE); |
| } |
| |
| setlocale(LC_ALL, ""); |
| printf("rpmatch() returns: %d\\n", rpmatch(argv[1])); |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .SH SEE ALSO |
| .BR fgets (3), |
| .BR getline (3), |
| .BR nl_langinfo (3), |
| .BR regcomp (3), |
| .BR setlocale (3) |