Debian Codegraph @

upstream/debian-unstable/man3/rpmatch.3

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