mirror of https://github.com/mkerrisk/man-pages
133 lines
4.0 KiB
Groff
133 lines
4.0 KiB
Groff
.\" Copyright (C) 2006 Justin Pryzby <pryzbyj@justinpryzby.com>
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" References:
|
|
.\" glibc manual and source
|
|
.\"
|
|
.\" 2006-05-19, mtk, various edits and example program
|
|
.\"
|
|
.TH RPMATCH 3 2007-07-26 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
rpmatch \- determine if the answer to a question is affirmative or negative
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <stdlib.h>
|
|
|
|
\fBint rpmatch(const char *\fIresponse\fB);
|
|
.fi
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.BR rpmatch ():
|
|
_SVID_SOURCE
|
|
.SH DESCRIPTION
|
|
.BR rpmatch ()
|
|
handles a user response to yes or no questions, with
|
|
support for internationalization.
|
|
|
|
\fIresponse\fP should be a null-terminated string containing a
|
|
user-supplied response, perhaps obtained with
|
|
.BR fgets (3)
|
|
or
|
|
.BR getline (3).
|
|
|
|
The user's language preference is taken into account per the
|
|
environment variables \fBLANG\fP, \fBLC_MESSAGES\fP, and \fBLC_ALL\fP,
|
|
if the program has called
|
|
.BR setlocale (3)
|
|
to effect their changes.
|
|
|
|
Regardless of the locale, responses matching \fB^[Yy]\fP are always
|
|
accepted as affirmative, and those matching \fB^[Nn]\fP 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 \fIresponse\fP 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 non-zero.
|
|
|
|
.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 \fIerrno\fP or anywhere else, but indicates a
|
|
failure of the regex engine (but this case is indistinguishable from
|
|
that of an unrecognized value of \fIresponse\fP).
|
|
.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 \fIresponse\fP.
|
|
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)):
|
|
\fB^([yY]|yes|YES)$\fP and \fB^([nN]|no|NO)$\fP.
|
|
.SH EXAMPLE
|
|
The following program displays the results when
|
|
.BR rpmatch ()
|
|
is applied to the string given in the program's command-line argument.
|
|
.nf
|
|
|
|
#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);
|
|
}
|
|
.fi
|
|
.SH SEE ALSO
|
|
.BR regcomp (3),
|
|
.BR fgets (3),
|
|
.BR getline (3),
|
|
.BR nl_langinfo (3),
|
|
.BR setlocale (3)
|