Debian Codegraph @

upstream/debian-trixie/man3/rpmatch.3

raw
1 '\" t
2 .\" Copyright (C) 2006 Justin Pryzby <[email protected]>
3 .\"
4 .\" %%%LICENSE_START(PERMISSIVE_MISC)
5 .\" Permission is hereby granted, free of charge, to any person obtaining
6 .\" a copy of this software and associated documentation files (the
7 .\" "Software"), to deal in the Software without restriction, including
8 .\" without limitation the rights to use, copy, modify, merge, publish,
9 .\" distribute, sublicense, and/or sell copies of the Software, and to
10 .\" permit persons to whom the Software is furnished to do so, subject to
11 .\" the following conditions:
12 .\"
13 .\" The above copyright notice and this permission notice shall be
14 .\" included in all copies or substantial portions of the Software.
15 .\"
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19 .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
20 .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
21 .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
22 .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 .\" %%%LICENSE_END
24 .\"
25 .\" References:
26 .\" glibc manual and source
27 .\"
28 .\" 2006-05-19, mtk, various edits and example program
29 .\"
30 .TH rpmatch 3 2024-06-15 "Linux man-pages 6.9.1"
31 .SH NAME
32 rpmatch \- determine if the answer to a question is affirmative or negative
33 .SH LIBRARY
34 Standard C library
35 .RI ( libc ", " \-lc )
36 .SH SYNOPSIS
37 .nf
38 .B #include <stdlib.h>
39 .P
40 .BI "int rpmatch(const char *" response );
41 .fi
42 .P
43 .RS -4
44 Feature Test Macro Requirements for glibc (see
45 .BR feature_test_macros (7)):
46 .RE
47 .P
48 .BR rpmatch ():
49 .nf
50 Since glibc 2.19:
51 _DEFAULT_SOURCE
52 glibc 2.19 and earlier:
53 _SVID_SOURCE
54 .fi
55 .SH DESCRIPTION
56 .BR rpmatch ()
57 handles a user response to yes or no questions, with
58 support for internationalization.
59 .P
60 .I response
61 should be a null-terminated string containing a
62 user-supplied response, perhaps obtained with
63 .BR fgets (3)
64 or
65 .BR getline (3).
66 .P
67 The user's language preference is taken into account per the
68 environment variables
69 .BR LANG ,
70 .BR LC_MESSAGES ,
71 and
72 .BR LC_ALL ,
73 if the program has called
74 .BR setlocale (3)
75 to effect their changes.
76 .P
77 Regardless of the locale, responses matching
78 .B \[ha][Yy]
79 are always accepted as affirmative, and those matching
80 .B \[ha][Nn]
81 are always accepted as negative.
82 .SH RETURN VALUE
83 After examining
84 .IR response ,
85 .BR rpmatch ()
86 returns 0 for a recognized negative response ("no"), 1
87 for a recognized positive response ("yes"), and \-1 when the value
88 of
89 .I response
90 is unrecognized.
91 .SH ERRORS
92 A return value of \-1 may indicate either an invalid input, or some
93 other error.
94 It is incorrect to only test if the return value is nonzero.
95 .P
96 .BR rpmatch ()
97 can fail for any of the reasons that
98 .BR regcomp (3)
99 or
100 .BR regexec (3)
101 can fail; the cause of the error
102 is not available from
103 .I errno
104 or anywhere else, but indicates a
105 failure of the regex engine (but this case is indistinguishable from
106 that of an unrecognized value of
107 .IR response ).
108 .SH ATTRIBUTES
109 For an explanation of the terms used in this section, see
110 .BR attributes (7).
111 .TS
112 allbox;
113 lbx lb lb
114 l l l.
115 Interface Attribute Value
116 T{
117 .na
118 .nh
119 .BR rpmatch ()
120 T} Thread safety MT-Safe locale
121 .TE
122 .SH STANDARDS
123 None.
124 .SH HISTORY
125 GNU, FreeBSD, AIX.
126 .SH BUGS
127 The
128 .BR YESEXPR " and " NOEXPR
129 of some locales (including "C") only inspect the first character of the
130 .IR response .
131 This can mean that "yno" et al. resolve to
132 .BR 1 .
133 This is an unfortunate historical side-effect which should be fixed in time
134 with proper localisation, and should not deter from
135 .BR rpmatch ()
136 being the proper way to distinguish between binary answers.
137 .SH EXAMPLES
138 The following program displays the results when
139 .BR rpmatch ()
140 is applied to the string given in the program's command-line argument.
141 .P
142 .\" SRC BEGIN (rpmatch.c)
143 .EX
144 #define _DEFAULT_SOURCE
145 #include <locale.h>
146 #include <stdio.h>
147 #include <stdlib.h>
148 #include <string.h>
149 \&
150 int
151 main(int argc, char *argv[])
152 {
153 if (argc != 2 || strcmp(argv[1], "\-\-help") == 0) {
154 fprintf(stderr, "%s response\[rs]n", argv[0]);
155 exit(EXIT_FAILURE);
156 }
157 \&
158 setlocale(LC_ALL, "");
159 printf("rpmatch() returns: %d\[rs]n", rpmatch(argv[1]));
160 exit(EXIT_SUCCESS);
161 }
162 .EE
163 .\" SRC END
164 .SH SEE ALSO
165 .BR fgets (3),
166 .BR getline (3),
167 .BR nl_langinfo (3),
168 .BR regcomp (3),
169 .BR setlocale (3)