draft/man3/strtok.3

   1 .\" Copyright (C) 2005, 2013 Michael Kerrisk (mtk.manpages@gmail.com)
   2 .\" a few fragments from an earlier (1996) version by
   3 .\" Andries Brouwer (aeb@cwi.nl) remain.
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" Rewritten old page, 960210, aeb@cwi.nl
  28 .\" Updated, added strtok_r. 2000-02-13 Nicolás Lichtmaier <nick@debian.org>
  29 .\" 2005-11-17, mtk: Substantial parts rewritten
  30 .\" 2013-05-19, mtk: added much further detail on the operation of strtok()
  31 .\"
  32 .\"*******************************************************************
  33 .\"
  34 .\" This file was generated with po4a. Translate the source file.
  35 .\"
  36 .\"*******************************************************************
  37 .TH STRTOK 3 2013\-05\-19 GNU "Linux Programmer's Manual"
  38 .SH 名前
  39 strtok, strtok_r \- 文字列からトークンを取り出す
  40 .SH 書式
  41 .nf
  42 \fB#include <string.h>\fP
  43 .sp
  44 \fBchar *strtok(char *\fP\fIstr\fP\fB, const char *\fP\fIdelim\fP\fB);\fP
  45 .sp
  46 \fBchar *strtok_r(char *\fP\fIstr\fP\fB, const char *\fP\fIdelim\fP\fB, char **\fP\fIsaveptr\fP\fB);\fP
  47 .fi
  48 .sp
  49 .in -4n
  50 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  51 .in
  52 .sp
  53 .ad l
  54 \fBstrtok_r\fP(): _SVID_SOURCE || _BSD_SOURCE || _POSIX_C_SOURCE\ >=\ 1 ||
  55 _XOPEN_SOURCE || _POSIX_SOURCE
  56 .ad b
  57 .SH 説明
  58 \fBstrtok\fP()  関数は文字列を 0 個以上の空でないトークンの列に分割する。 \fBstrtok\fP()
  59 を最初に呼び出す際には、解析対象の文字列を \fIstr\fP に 指定する。同じ文字列の解析を行うその後の呼び出しでは、 \fIstr\fP は NULL
  60 にしなければならない。
  61
  62 \fIdelim\fP 引き数には、解析対象の文字列をトークンに区切るのに使用する
  63 バイト集合を指定する。同じ文字列を解析する一連の呼び出しにおいて、
  64 \fIdelim\fP に違う文字列を指定してもよい。
  65
  66 \fBstrtok\fP() のそれぞれの呼び出しでは、次のトークンを格納した NULL 終端
  67 された文字列へのポインタが返される。この文字列には区切りバイトは含まれ
  68 ない。これ以上トークンが見つからなかった場合には、NULL が返される。
  69
  70 A sequence of calls to \fBstrtok\fP()  that operate on the same string
  71 maintains a pointer that determines the point from which to start searching
  72 for the next token.  The first call to \fBstrtok\fP()  sets this pointer to
  73 point to the first byte of the string.  The start of the next token is
  74 determined by scanning forward for the next nondelimiter byte in \fIstr\fP.  If
  75 such a byte is found, it is taken as the start of the next token.  If no
  76 such byte is found, then there are no more tokens, and \fBstrtok\fP()  returns
  77 NULL.  (A string that is empty or that contains only delimiters will thus
  78 cause \fBstrtok\fP()  to return NULL on the first call.)
  79
  80 The end of each token is found by scanning forward until either the next
  81 delimiter byte is found or until the terminating null byte (\(aq\e0\(aq) is
  82 encountered.  If a delimiter byte is found, it is overwritten with a null
  83 byte to terminate the current token, and \fBstrtok\fP()  saves a pointer to the
  84 following byte; that pointer will be used as the starting point when
  85 searching for the next token.  In this case, \fBstrtok\fP()  returns a pointer
  86 to the start of the found token.
  87
  88 From the above description, it follows that a sequence of two or more
  89 contiguous delimiter bytes in the parsed string is considered to be a single
  90 delimiter, and that delimiter bytes at the start or end of the string are
  91 ignored.  Put another way: the tokens returned by \fBstrtok\fP()  are always
  92 nonempty strings.  Thus, for example, given the string "\fIaaa;;bbb,\fP",
  93 successive calls to \fBstrtok\fP()  that specify the delimiter string "\fI;,\fP"
  94 would return the strings "\fIaaa\fP" and "\fIbbb\fP", and then a NULL pointer.
  95
  96 \fBstrtok_r\fP()  関数は \fBstrtok\fP()  のリエントラント版である。 \fIsaveptr\fP 引き数は \fIchar\ *\fP
  97 変数へのポインタであり、 同じ文字列の解析を行う \fBstrtok_r\fP()  の呼び出し間で処理状況を保存するために \fBstrtok_r\fP()
  98 内部で使用される。
  99
 100 \fBstrtok_r\fP()  を最初に呼び出す際には、 \fIstr\fP は解析対象の文字列を指していなければならず、 \fIsaveptr\fP
 101 の値は無視される。それ以降の呼び出しでは、 \fIstr\fP は NULL とし、 \fIsaveptr\fP
 102 は前回の呼び出し以降変更しないようにしなければならない。
 103
 104 \fBstrtok_r\fP()  の呼び出し時に異なる \fIsaveptr\fP 引き数を指定することで、 異なる文字列の解析を同時に行うことができる。
 105 .SH 返り値
 106 \fBstrtok\fP()  と \fBstrtok_r\fP()  は次のトークンへのポインタか、 トークンがなければ NULL を返す。
 107 .SH 属性
 108 .SS "マルチスレッディング (pthreads(7) 参照)"
 109 The \fBstrtok\fP() 関数はスレッドセーフではない。
 110 .LP
 111 \fBstrtok_r\fP() 関数はスレッドセーフである。
 112 .SH 準拠
 113 .TP
 114 \fBstrtok\fP()
 115 SVr4, POSIX.1\-2001, 4.3BSD, C89, C99.
 116 .TP
 117 \fBstrtok_r\fP()
 118 POSIX.1\-2001.
 119 .SH バグ
 120 これらの関数を使うのは慎重に吟味すること。 使用する場合は、以下の点に注意が必要である。
 121 .IP * 2
 122 これらの関数はその最初の引数を変更する。
 123 .IP *
 124 これらの関数は const な文字列では使えない。
 125 .IP *
 126 区切りバイト自体は失われてしまう。
 127 .IP *
 128 \fBstrtok\fP()  関数は文字列の解析に静的バッファを用いるので、スレッドセーフでない。 これが問題になる場合は \fBstrtok_r\fP()
 129 を用いること。
 130 .SH 例
 131 以下のプログラムは、 \fBstrtok_r\fP() を利用するループを入れ子にして使用し、
 132 文字列を 2 階層のトークンに分割するものである。 1番目のコマンドライン
 133 引き数には、解析対象の文字列を指定する。 2 番目の引き数には、文字列を
 134 「大きな」トークンに分割するために 使用する区切りバイトを指定する。
 135 3 番目の引き数には、「大きな」トークンを細かく分割するために使用する
 136 区切りバイトを指定する。
 137 .PP
 138 このプログラムの出力例を以下に示す。
 139 .PP
 140 .in +4n
 141 .nf
 142 $\fB ./a.out \(aqa/bbb///cc;xxx:yyy:\(aq \(aq:;\(aq \(aq/\(aq\fP
 143 1: a/bbb///cc
 144          \-\-> a
 145          \-\-> bbb
 146          \-\-> cc
 147 2: xxx
 148          \-\-> xxx
 149 3: yyy
 150          \-\-> yyy
 151 .fi
 152 .in
 153 .SS プログラムのソース
 154 \&
 155 .nf
 156 #include <stdio.h>
 157 #include <stdlib.h>
 158 #include <string.h>
 159
 160 int
 161 main(int argc, char *argv[])
 162 {
 163     char *str1, *str2, *token, *subtoken;
 164     char *saveptr1, *saveptr2;
 165     int j;
 166
 167     if (argc != 4) {
 168         fprintf(stderr, "Usage: %s string delim subdelim\en",
 169                 argv[0]);
 170         exit(EXIT_FAILURE);
 171     }
 172
 173     for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
 174         token = strtok_r(str1, argv[2], &saveptr1);
 175         if (token == NULL)
 176             break;
 177         printf("%d: %s\en", j, token);
 178
 179         for (str2 = token; ; str2 = NULL) {
 180             subtoken = strtok_r(str2, argv[3], &saveptr2);
 181             if (subtoken == NULL)
 182                 break;
 183             printf("\t \-\-> %s\en", subtoken);
 184         }
 185     }
 186
 187     exit(EXIT_SUCCESS);
 188 }
 189 .fi
 190 .PP
 191 \fBstrtok\fP()  を使った別のプログラム例が \fBgetaddrinfo_a\fP(3)  にある。
 192 .SH 関連項目
 193 \fBindex\fP(3), \fBmemchr\fP(3), \fBrindex\fP(3), \fBstrchr\fP(3), \fBstring\fP(3),
 194 \fBstrpbrk\fP(3), \fBstrsep\fP(3), \fBstrspn\fP(3), \fBstrstr\fP(3), \fBwcstok\fP(3)
 195 .SH この文書について
 196 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 197 である。プロジェクトの説明とバグ報告に関する情報は
 198 http://www.kernel.org/doc/man\-pages/ に書かれている。