]>
Commit | Line | Data |
---|---|---|
d2b53444 MK |
1 | .\" Copyright (C) 2006 Justin Pryzby <pryzbyj@justinpryzby.com> |
2 | .\" | |
3 | .\" Permission is hereby granted, free of charge, to any person obtaining | |
4 | .\" a copy of this software and associated documentation files (the | |
5 | .\" "Software"), to deal in the Software without restriction, including | |
6 | .\" without limitation the rights to use, copy, modify, merge, publish, | |
7 | .\" distribute, sublicense, and/or sell copies of the Software, and to | |
8 | .\" permit persons to whom the Software is furnished to do so, subject to | |
9 | .\" the following conditions: | |
10 | .\" | |
11 | .\" The above copyright notice and this permission notice shall be | |
12 | .\" included in all copies or substantial portions of the Software. | |
13 | .\" | |
14 | .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, | |
15 | .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF | |
16 | .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. | |
17 | .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY | |
18 | .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, | |
19 | .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE | |
20 | .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
21 | .\" | |
22 | .\" References: | |
23 | .\" glibc manual and source | |
6a39becb | 24 | .\" |
451d74fc | 25 | .\" 2006-05-19, mtk, various edits and example program |
6a39becb | 26 | .\" |
05eabe65 | 27 | .TH RPMATCH 3 2006-05-17 "GNU" "Linux Programmer's Manual" |
d2b53444 MK |
28 | .SH NAME |
29 | rpmatch \- determine if the answer to a question is affirmative or negative | |
30 | .SH SYNOPSIS | |
3b158837 | 31 | .nf |
d2b53444 MK |
32 | \fB#define _SVID_SOURCE |
33 | \fB#include <stdlib.h> | |
34 | ||
b9f02710 | 35 | \fBint rpmatch(const char *\fIresponse\fB); |
3b158837 | 36 | .fi |
d2b53444 | 37 | .SH DESCRIPTION |
60a90ecd MK |
38 | .BR rpmatch () |
39 | handles a user response to yes or no questions, with | |
c13182ef | 40 | support for internationalization. |
d2b53444 MK |
41 | |
42 | \fIresponse\fP should be a null-terminated string containing a | |
60a90ecd MK |
43 | user-supplied response, perhaps obtained with |
44 | .BR fgets (3) | |
45 | or | |
46 | .BR getline (3). | |
6a39becb MK |
47 | |
48 | The user's language preference is taken into account per the | |
49 | environment variables \fBLANG\fP, \fBLC_MESSAGES\fP, and \fBLC_ALL\fP, | |
60a90ecd MK |
50 | if the program has called |
51 | .BR setlocale (3) | |
52 | to effect their changes. | |
3e2984b2 | 53 | |
c13182ef MK |
54 | Regardless of the locale, responses matching \fB^[Yy]\fP are always |
55 | accepted as affirmative, and those matching \fB^[Nn]\fP are always | |
3e2984b2 | 56 | accepted as negative. |
d2b53444 | 57 | .SH "RETURN VALUE" |
c13182ef MK |
58 | After examining |
59 | .IR response , | |
60a90ecd MK |
60 | .BR rpmatch () |
61 | returns 0 for a recognized negative response ("no"), 1 | |
d2b53444 MK |
62 | for a recognized positive response ("yes"), and \-1 when the value |
63 | of \fIresponse\fP is unrecognized. | |
64 | .SH ERRORS | |
65 | A return value of \-1 may indicate either an invalid input, or some | |
c13182ef MK |
66 | other error. |
67 | It is incorrect to only test if the return value is nonzero. | |
6a39becb | 68 | |
60a90ecd MK |
69 | .BR rpmatch () |
70 | can fail for any of the reasons that | |
71 | .BR regcomp (3) | |
72 | or | |
73 | .BR regexec (3) | |
74 | can fail; the cause of the error | |
d2b53444 MK |
75 | is not available from \fIerrno\fP or anywhere else, but indicates a |
76 | failure of the regex engine (but this case is indistinguishable from | |
77 | that of an unrecognized value of \fIresponse\fP). | |
78 | .SH "CONFORMING TO" | |
60a90ecd MK |
79 | .BR rpmatch () |
80 | is not required by any standard, but | |
d2b53444 MK |
81 | is available on a few other systems. |
82 | .\" It is available on at least AIX 5.1 and FreeBSD 6.0. | |
83 | .SH BUGS | |
60a90ecd MK |
84 | The |
85 | .BR rpmatch () | |
86 | implementation looks at only the first character | |
c13182ef MK |
87 | of \fIresponse\fP. |
88 | As a consequence, "nyes" returns 0, and | |
d2b53444 MK |
89 | "ynever; not in a million years" returns 1. |
90 | It would be preferable to accept input strings much more | |
c13182ef | 91 | strictly, for example (using the extended regular |
60a90ecd MK |
92 | expression notation described in |
93 | .BR regex (7)): | |
3e2984b2 | 94 | \fB^([yY]|yes|YES)$\fP and \fB^([nN]|no|NO)$\fP. |
3721893a | 95 | .SH EXAMPLE |
d2b53444 MK |
96 | The following program displays the results when |
97 | .BR rpmatch () | |
98 | is applied to the string given in the program's command-line argument. | |
99 | .nf | |
100 | ||
101 | #define _SVID_SOURCE | |
102 | #include <locale.h> | |
103 | #include <stdlib.h> | |
104 | #include <string.h> | |
105 | #include <stdio.h> | |
106 | ||
107 | int | |
108 | main(int argc, char *argv[]) | |
109 | { | |
29059a65 | 110 | if (argc != 2 || strcmp(argv[1], "\-\-help") == 0) { |
d2b53444 MK |
111 | fprintf(stderr, "%s response\\n", argv[0]); |
112 | exit(EXIT_FAILURE); | |
c13182ef | 113 | } |
d2b53444 MK |
114 | |
115 | setlocale(LC_ALL, ""); | |
116 | printf("rpmatch() returns: %d\\n", rpmatch(argv[1])); | |
117 | exit(EXIT_SUCCESS); | |
118 | } | |
119 | .fi | |
120 | .SH SEE ALSO | |
d2b53444 MK |
121 | .BR regcomp (3), |
122 | .BR fgets (3), | |
123 | .BR getline (3), | |
124 | .BR nl_langinfo (3), | |
0a90178c MK |
125 | .BR setlocale (3), |
126 | .BR feature_test_macros (7) |