draft/man3/rpmatch.3

   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
  24 .\"
  25 .\" 2006-05-19, mtk, various edits and example program
  26 .\"
  27 .\" Japanese Version Copyright (c) 2006 Akihiro MOTOKI all rights reserved.
  28 .\" Translated 2006-07-31, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  29 .\"
  30 .TH RPMATCH 3 2007-07-26 "GNU" "Linux Programmer's Manual"
  31 .\"O .SH NAME
  32 .SH 名前
  33 .\"O rpmatch \- determine if the answer to a question is affirmative or negative
  34 rpmatch \- 質問への応答が肯定か否定かを判定する
  35 .\"O .SH SYNOPSIS
  36 .SH 書式
  37 .nf
  38 .B #include <stdlib.h>
  39
  40 .BI "int rpmatch(const char *" response );
  41 .fi
  42 .sp
  43 .in -4n
  44 .\"O Feature Test Macro Requirements for glibc (see
  45 .\"O .BR feature_test_macros (7)):
  46 glibc 向けの機能検査マクロの要件
  47 .RB ( feature_test_macros (7)
  48 参照):
  49 .in
  50 .sp
  51 .BR rpmatch ():
  52 _SVID_SOURCE
  53 .\"O .SH DESCRIPTION
  54 .SH 説明
  55 .\"O .BR rpmatch ()
  56 .\"O handles a user response to yes or no questions, with
  57 .\"O support for internationalization.
  58 .BR  rpmatch ()
  59 は yes/no の質問に対するユーザからの応答を処理する。
  60 国際化 (I18N) に対応している。
  61
  62 .\"O \fIresponse\fP should be a null-terminated string containing a
  63 .\"O user-supplied response, perhaps obtained with
  64 .\"O .BR fgets (3)
  65 .\"O or
  66 .\"O .BR getline (3).
  67 .I response
  68 にはユーザからの応答を格納した NULL 終端文字列が入っている必要がある。
  69 たいていは、
  70 .BR fgets (3)
  71 や
  72 .BR getline (3)
  73 で取り込んだものであろう。
  74
  75 .\"O The user's language preference is taken into account per the
  76 .\"O environment variables \fBLANG\fP, \fBLC_MESSAGES\fP, and \fBLC_ALL\fP,
  77 .\"O if the program has called
  78 .\"O .BR setlocale (3)
  79 .\"O to effect their changes.
  80 プログラムが
  81 .BR setlocale (3)
  82 を呼び出して環境変数の変更を有効にした場合、
  83 環境変数 \fBLANG\fP, \fBLC_MESSAGES\fP, \fBLC_ALL\fP が
  84 ユーザの言語設定として考慮される。
  85
  86 .\"O Regardless of the locale, responses matching \fB^[Yy]\fP are always
  87 .\"O accepted as affirmative, and those matching \fB^[Nn]\fP are always
  88 .\"O accepted as negative.
  89 ロケールに関わらず、\fB^[Yy]\fP にマッチする応答は常に肯定だと解釈され、
  90 \fB^[Nn]\fP にマッチする応答は常に否定だと解釈される。
  91 .\"O .SH "RETURN VALUE"
  92 .SH 返り値
  93 .\"O After examining
  94 .\"O .IR response ,
  95 .\"O .BR rpmatch ()
  96 .\"O returns 0 for a recognized negative response ("no"), 1
  97 .\"O for a recognized positive response ("yes"), and \-1 when the value
  98 .\"O of \fIresponse\fP is unrecognized.
  99 .I response
 100 を検査した後、
 101 .BR rpmatch ()
 102 は否定的な応答 ("no") と認識した場合は 0 を返し、
 103 肯定的な応答 ("yes") と認識した場合は 1 を返す。
 104 .I response
 105 の値を解釈できなかった場合は \-1 を返す。
 106 .\"O .SH ERRORS
 107 .SH エラー
 108 .\"O A return value of \-1 may indicate either an invalid input, or some
 109 .\"O other error.
 110 .\"O It is incorrect to only test if the return value is nonzero.
 111 返り値 \-1 が返った場合、入力が不正であったか、他の何らかのエラーが
 112 あったことを意味する。返り値が 0 以外かどうかを確認するだけでは
 113 十分ではない。
 114
 115 .\"O .BR rpmatch ()
 116 .\"O can fail for any of the reasons that
 117 .\"O .BR regcomp (3)
 118 .\"O or
 119 .\"O .BR regexec (3)
 120 .\"O can fail; the cause of the error
 121 .\"O is not available from \fIerrno\fP or anywhere else, but indicates a
 122 .\"O failure of the regex engine (but this case is indistinguishable from
 123 .\"O that of an unrecognized value of \fIresponse\fP).
 124 .BR rpmatch ()
 125 は、
 126 .BR regcomp (3)
 127 や
 128 .BR regexec (3)
 129 が失敗する理由のどれかで失敗することがある。
 130 エラーの原因を
 131 .I errno
 132 や他の何かで知ることはできないが、
 133 .I errno
 134 は正規表現エンジンの失敗の原因を示している
 135 (但し、このケースと
 136 .I response
 137 の値を認識できずに失敗した場合を区別することはできない)。
 138 .\"O .SH "CONFORMING TO"
 139 .SH 準拠
 140 .\"O .BR rpmatch ()
 141 .\"O is not required by any standard, but
 142 .\"O is available on a few other systems.
 143 .BR rpmatch ()
 144 はどの標準でも必須となっていないが、
 145 Linux 以外にも利用できるシステムもいくつかは存在する。
 146 .\"O .\" It is available on at least AIX 5.1 and FreeBSD 6.0.
 147 .\" 少なくとも AIX 5.1 と FreeBSD 6.0 では利用できる。
 148 .\"O .SH BUGS
 149 .SH バグ
 150 .\"O The
 151 .\"O .BR rpmatch ()
 152 .\"O implementation looks at only the first character
 153 .\"O of \fIresponse\fP.
 154 .\"O As a consequence, "nyes" returns 0, and
 155 .\"O "ynever; not in a million years" returns 1.
 156 .\"O It would be preferable to accept input strings much more
 157 .\"O strictly, for example (using the extended regular
 158 .\"O expression notation described in
 159 .\"O .BR regex (7)):
 160 .\"O \fB^([yY]|yes|YES)$\fP and \fB^([nN]|no|NO)$\fP.
 161 .BR rpmatch ()
 162 の実装は
 163 .I response
 164 の最初の 1 文字だけを見ているようである。その結果、
 165 "nyes" は 0 を返し、
 166 "ynever; not in a million years" は 1 を返すことになる。
 167 入力文字列をもっと厳密に解釈した方がよいだろう。
 168 例えば、
 169 .RB ( regex (7)
 170 で説明されている拡張正規表現を使って)
 171 .BR ^([yY]|yes|YES)$ " や " ^([nN]|no|NO)$
 172 で解釈するなど。
 173 .\"O .SH EXAMPLE
 174 .SH 例
 175 .\"O The following program displays the results when
 176 .\"O .BR rpmatch ()
 177 .\"O is applied to the string given in the program's command-line argument.
 178 以下のプログラムは、コマンドライン引き数で
 179 指定された文字列を
 180 .BR rpmatch ()
 181 に渡した場合の結果を表示する。
 182 .nf
 183
 184 #define _SVID_SOURCE
 185 #include <locale.h>
 186 #include <stdlib.h>
 187 #include <string.h>
 188 #include <stdio.h>
 189
 190 int
 191 main(int argc, char *argv[])
 192 {
 193     if (argc != 2 || strcmp(argv[1], "\-\-help") == 0) {
 194         fprintf(stderr, "%s response\\n", argv[0]);
 195         exit(EXIT_FAILURE);
 196     }
 197
 198     setlocale(LC_ALL, "");
 199     printf("rpmatch() returns: %d\\n", rpmatch(argv[1]));
 200     exit(EXIT_SUCCESS);
 201 }
 202 .fi
 203 .\"O .SH SEE ALSO
 204 .SH 関連項目
 205 .BR fgets (3),
 206 .BR getline (3),
 207 .BR nl_langinfo (3),
 208 .BR regcomp (3),
 209 .BR setlocale (3)