manual/LDP_man-pages/draft/man3/regex.3

   1 .\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@ee.surrey.ac.uk)
  26 .\" Tiny change in formatting - aeb, 950812
  27 .\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
  28 .\"
  29 .\" show the synopsis section nicely
  30 .\"*******************************************************************
  31 .\"
  32 .\" This file was generated with po4a. Translate the source file.
  33 .\"
  34 .\"*******************************************************************
  35 .\"
  36 .\" Japanese Version Copyright (c) 1998 Takatsugu Nokubi
  37 .\"     all rights reserved.
  38 .\" Translated 1998-06-30, Takatsugu Nokubi
  39 .\" Updated & Modified 2001-11-05, Yuichi SATO <ysato@h4.dion.ne.jp>
  40 .\" Updated & Modified 2005-02-24, Yuichi SATO <ysato444@yahoo.co.jp>
  41 .\" Updated 2008-08-02, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.05
  42 .\" Updated 2013-03-27, Akihiro MOTOKI <amotoki@gmail.com>
  43 .\"
  44 .TH REGEX 3 2020\-08\-13 GNU "Linux Programmer's Manual"
  45 .SH 名前
  46 regcomp, regexec, regerror, regfree \- POSIX regex 関数
  47 .SH 書式
  48 .nf
  49 \fB#include <regex.h>\fP
  50 .PP
  51 \fBint regcomp(regex_t *\fP\fIpreg\fP\fB, const char *\fP\fIregex\fP\fB, int \fP\fIcflags\fP\fB);\fP
  52 .PP
  53 \fBint regexec(const regex_t *\fP\fIpreg\fP\fB, const char *\fP\fIstring\fP\fB, size_t \fP\fInmatch\fP\fB,\fP
  54 \fB            regmatch_t \fP\fIpmatch[]\fP\fB, int \fP\fIeflags\fP\fB);\fP
  55 .PP
  56 \fBsize_t regerror(int \fP\fIerrcode\fP\fB, const regex_t *\fP\fIpreg\fP\fB, char *\fP\fIerrbuf\fP\fB,\fP
  57 \fB                size_t \fP\fIerrbuf_size\fP\fB);\fP
  58 .PP
  59 \fBvoid regfree(regex_t *\fP\fIpreg\fP\fB);\fP
  60 .fi
  61 .SH 説明
  62 .SS "POSIX regex コンパイル"
  63 \fBregcomp\fP()  は、正規表現をコンパイルして、 \fBregexec\fP()  での検索処理に適合する形態にする。
  64 .PP
  65 \fBregcomp\fP()  はパターンを記憶するバッファーへのポインター \fIpreg\fP、 ヌル文字で終端された文字列 \fIregex\fP、
  66 そしてコンパイルの形式を決めるためのフラグ \fIcflag\fP を引数に伴う。
  67 .PP
  68 全ての正規表現検索は、コンパイルされたパターンによって行わなければならない。 よって、 \fBregexec\fP()  に指定するのは、必ず
  69 (\fBregcomp\fP()  によってコンパイルされた) パターンバッファーへのアドレスでなければならない。
  70 .PP
  71 \fIcflags\fP には、以下に示す定数のうち 0 個以上をビットごとの OR (bitwise\-or) で指定する。
  72 .TP
  73 \fBREG_EXTENDED\fP
  74 \fIregex\fP に \fBPOSIX\fP 拡張正規表現を使用する。もしこのフラグが設定されない場合、 \fBPOSIX\fP 標準正規表現が使われる。
  75 .TP
  76 \fBREG_ICASE\fP
  77 大文字小文字の違いを無視する。このフラグを指定してコンパイルされた パターンバッファーを用いて \fBregexec\fP()
  78 関数を呼び出すと、大文字小文字の区別を付けずに検索が行われる。
  79 .TP
  80 \fBREG_NOSUB\fP
  81 マッチの場所を報告しない。渡されたパターンバッファーがこのフラグを設定してコンパイルされていた場合、 \fBregexec\fP() の引き数
  82 \fInmatch\fP, \fIpmatch\fP が無視される。
  83 .TP
  84 \fBREG_NEWLINE\fP
  85 全ての文字にマッチするオペレータに改行をマッチさせない。
  86 .IP
  87 改行を含まない非マッチング文字リスト (\fB[\(ha...]\fP)  に改行をマッチさせない。
  88 .IP
  89 \fBregexec\fP()  の実行時に指定するフラグ \fIeflags\fP に \fBREG_NOTBOL\fP
  90 を含むかどうかにかかわらず、行頭にマッチするオペレータ (\fB\(ha\fP)  を改行直後の空文字列にマッチさせる。
  91 .IP
  92 \fIeflags\fP に \fBREG_NOTEOL\fP を含むかどうかにかかわらず、行末にマッチするオペレータ (\fB$\fP)
  93 を改行直前の空文字列にマッチさせる。
  94 .SS "POSIX regex マッチング"
  95 \fBregexec\fP()  は、 プリコンパイルされたパターンバッファー \fIpreg\fP をヌル文字で終端された文字列にマッチさせる。
  96 \fInmatch\fP と \fIpmatch\fP はマッチングの位置に関する情報を取得するのに用いられる。 \fIeflags\fP には、以下のフラグのうち 0
  97 個以上をビットごとの \fBOR\fP (bitwise\-\fBor\fP) で指定する。
  98 .TP
  99 \fBREG_NOTBOL\fP
 100 行頭にマッチするオペレータは、必ずマッチに失敗する (コンパイル時のフラグ \fBREG_NEWLINE\fP の項目も参照)。
 101 このフラグは、複数行にまたがる文字列を \fBregexec\fP()  で検索する際に、文字列の先頭を行の先頭として解釈させない場合に用いる。
 102 .TP
 103 \fBREG_NOTEOL\fP
 104 行末にマッチするオペレータは、必ずマッチに失敗する (コンパイル時のフラグ \fBREG_NEWLINE\fP の項目も参照)。
 105 .TP
 106 \fBREG_STARTEND\fP
 107 Use \fIpmatch[0]\fP on the input string, starting at byte \fIpmatch[0].rm_so\fP
 108 and ending before byte \fIpmatch[0].rm_eo\fP.  This allows matching embedded
 109 NUL bytes and avoids a \fBstrlen\fP(3)  on large strings.  It does not use
 110 \fInmatch\fP on input, and does not change \fBREG_NOTBOL\fP or \fBREG_NEWLINE\fP
 111 processing.  This flag is a BSD extension, not present in POSIX.
 112 .SS バイトオフセット
 113 パターンバッファーのコンパイル時に \fBREG_NOSUB\fP が設定されない場合は、マッチング位置情報を得ることができる。 \fIpmatch\fP
 114 は、少なくとも \fInmatch\fP の大きさを持つように指定しなければならない。 \fBregexec\fP()
 115 の実行によって、それらに部分文字列マッチング位置情報が代入される。 \fIi\fP 番目の括弧で始まる部分正規表現のオフセットは \fIpmatch[i]\fP
 116 に格納される。正規表現全体のマッチアドレスは \fIpmatch[0]\fP に格納される。 (\fIN\fP 個の部分正規表現のマッチのオフセットを返すためには、
 117 \fInmatch\fP は最低限 \fIN+1\fP でなければならない点に注意すること。) 未使用の構造体要素には \-1 が値として代入される。
 118 .PP
 119 \fIpmatch\fP の型である \fIregmatch_t\fP 構造体は、 \fI<regex.h>\fP 内で定義される。
 120 .PP
 121 .in +4n
 122 .EX
 123 typedef struct {
 124     regoff_t rm_so;
 125     regoff_t rm_eo;
 126 } regmatch_t;
 127 .EE
 128 .in
 129 .PP
 130 構造体要素 \fIrm_so\fP の値が \-1 でない場合、それは文字列内での次の最大のマッチング部分の開始 オフセット位置を示す。それに対し、構造体要素
 131 \fIrm_eo\fP はマッチング部分の終了オフセット位置を示し、 マッチング部分の直後の文字のオフセット位置が使用される。
 132 .SS "POSIX エラーレポート"
 133 \fBregerror\fP()  は、 \fBregcomp\fP()  と \fBregexec\fP()
 134 の実行によって得られるエラーコードから、エラーメッセージ文字列を 得るのに用いられる。
 135 .PP
 136 \fBregerror\fP()  はエラーコード \fIerrcode\fP、 パターンバッファー \fIpreg\fP、 文字列バッファーへのポインター
 137 \fIerrbuf\fP、 文字列バッファーのサイズ \fIerrbuf_size\fP を引数にとる。
 138 この関数は、ヌル文字で終端されたエラーメッセージ文字列を格納するのに必要な \fIerrbuf\fP のサイズを返す。もし \fIerrbuf\fP と
 139 \fIerrbuf_size\fP の両方が非 0 値であれば、 \fIerrbuf\fP には最初の \fIerrbuf_size \- 1\fP
 140 文字分にエラーメッセージと終端のヌルバイト (\(aq\e0\(aq)  が収まるように代入される。
 141 .SS "POSIX パターンバッファー解放"
 142 引数にコンパイルされたパターンバッファー \fIpreg\fP を与えて \fBregfree\fP()  を呼び出すと、 \fBregcomp\fP()
 143 によるコンパイル時にパターンバッファーに割り当てられたメモリーが解放される。
 144 .SH 返り値
 145 \fBregcomp\fP()  は、コンパイルの成功時には 0 を返し、失敗時にはエラーコードを返す。
 146 .PP
 147 \fBregexec\fP()  は、マッチングの成功時には 0 を返し、失敗時には \fBREG_NOMATCH\fP を返す。
 148 .SH エラー
 149 \fBregcomp\fP()  は以下のエラーを返す。
 150 .TP
 151 \fBREG_BADBR\fP
 152 無効な後方参照オペレータの使用。
 153 .TP
 154 \fBREG_BADPAT\fP
 155 グループやリストなどの、パターンオペレータの無効な使用。
 156 .TP
 157 \fBREG_BADRPT\fP
 158 \(aq*\(aq が最初の文字としてくるような、無効な繰り返しオペレータの使用。
 159 .TP
 160 \fBREG_EBRACE\fP
 161 インターバルオペレータ \fB{}\fP (brace interval operators) が閉じていない。
 162 .TP
 163 \fBREG_EBRACK\fP
 164 リストオペレータ \fB[]\fP (bracket list operators) が閉じていない。
 165 .TP
 166 \fBREG_ECOLLATE\fP
 167 照合順序の要素 (collating element) として有効ではない。 (訳注) 詳細は \fBregex\fP(7)  を参照。
 168 .TP
 169 \fBREG_ECTYPE\fP
 170 未知のキャラクタークラス名。
 171 .TP
 172 \fBREG_EEND\fP
 173 未定義エラー。これは POSIX.2 には定義されていない。
 174 .TP
 175 \fBREG_EESCAPE\fP
 176 正規表現がバックスラッシュで終っている。
 177 .TP
 178 \fBREG_EPAREN\fP
 179 グループオペレータ \fB()\fP (parenthesis group operators) が閉じていない。
 180 .TP
 181 \fBREG_ERANGE\fP
 182 無効な範囲オペレータの使用。 例えば、範囲の終了位置が開始位置よりも前にあるような場合。
 183 .TP
 184 \fBREG_ESIZE\fP
 185 正規表現のコンパイルに、64\ Kb 以上のパターンバッファーが必要。 これは POSIX.2 には定義されていない。
 186 .TP
 187 \fBREG_ESPACE\fP
 188 regex ルーチンがメモリーを使いはたしている。
 189 .TP
 190 \fBREG_ESUBREG\fP
 191 サブエクスプレッション \e\fB(...\e\fP)  (subexpression) への無効な後方参照。
 192 .SH 属性
 193 この節で使用されている用語の説明については、 \fBattributes\fP(7) を参照。
 194 .TS
 195 allbox;
 196 lbw20 lb lb
 197 l l l.
 198 インターフェース        属性  値
 199 T{
 200 \fBregcomp\fP(),
 201 \fBregexec\fP()
 202 T}      Thread safety   MT\-Safe locale
 203 T{
 204 \fBregerror\fP()
 205 T}      Thread safety   MT\-Safe env
 206 T{
 207 \fBregfree\fP()
 208 T}      Thread safety   MT\-Safe
 209 .TE
 210 .SH 準拠
 211 POSIX.1\-2001, POSIX.1\-2008.
 212 .SH 例
 213 .EX
 214 #include <stdint.h>
 215 #include <stdio.h>
 216 #include <stdlib.h>
 217 #include <regex.h>
 218
 219 #define ARRAY_SIZE(arr) (sizeof((arr)) / sizeof((arr)[0]))
 220
 221 static const char *const str =
 222         "1) John Driverhacker;\en2) John Doe;\en3) John Foo;\en";
 223 static const char *const re = "John.*o";
 224
 225 int main(void)
 226 {
 227     static const char *s = str;
 228     regex_t     regex;
 229     regmatch_t  pmatch[1];
 230     regoff_t    off, len;
 231
 232     if (regcomp(&regex, re, REG_NEWLINE))
 233         exit(EXIT_FAILURE);
 234
 235     printf("String = \e"%s\e"\en", str);
 236     printf("Matches:\en");
 237
 238     for (int i = 0; ; i++) {
 239         if (regexec(&regex, s, ARRAY_SIZE(pmatch), pmatch, 0))
 240             break;
 241
 242         off = pmatch[0].rm_so + (s \- str);
 243         len = pmatch[0].rm_eo \- pmatch[0].rm_so;
 244         printf("#%d:\en", i);
 245         printf("offset = %jd; length = %jd\en", (intmax_t) off,
 246                 (intmax_t) len);
 247         printf("substring = \e"%.*s\e"\en", len, s + pmatch[0].rm_so);
 248
 249         s += pmatch[0].rm_eo;
 250     }
 251
 252     exit(EXIT_SUCCESS);
 253 }
 254 .EE
 255 .SH 関連項目
 256 \fBgrep\fP(1), \fBregex\fP(7)
 257 .PP
 258 glibc マニュアルのセクション \fIRegular Expressions\fP
 259 .SH この文書について
 260 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
 261 \%https://www.kernel.org/doc/man\-pages/ に書かれている。