release/man3/strtok.3

   1 .\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl)
   2 .\" and Copyright (C) 2005 Michael Kerrisk (mtk.manpages@gmail.com)
   3 .\"
   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 .\"
  24 .\" Rewritten old page, 960210, aeb@cwi.nl
  25 .\" Updated, added strtok_r. 2000-02-13 Nicolas Lichtmaier <nick@debian.org>
  26 .\" 2005-11-17, mtk: Substantial parts rewritten
  27 .\"
  28 .\" Japanese Version Copyright (c) 1998 Ishii Tatsuo all rights reserved.
  29 .\" Translated 1998-03-27, Ishii Tatsuo <rfun@azusa.shinshu-u.ac.jp>
  30 .\" Updated 2000-04-05, Kentaro Shirakata <argrath@ub32.org>
  31 .\" Updated 2000-09-21, Kentaro Shirakata
  32 .\" Updated 2002-03-28, Kentaro Shirakata
  33 .\" Updated 2005-11-19, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  34 .\"
  35 .TH STRTOK 3  2010-09-27 "GNU" "Linux Programmer's Manual"
  36 .SH 名前
  37 strtok, strtok_r \- 文字列からトークンを取り出す
  38 .SH 書式
  39 .nf
  40 .B #include <string.h>
  41 .sp
  42 .BI "char *strtok(char *" str ", const char *" delim );
  43 .sp
  44 .BI "char *strtok_r(char *" str ", const char *" delim ", char **" saveptr );
  45 .fi
  46 .sp
  47 .in -4n
  48 glibc 向けの機能検査マクロの要件
  49 .RB ( feature_test_macros (7)
  50 参照):
  51 .in
  52 .sp
  53 .ad l
  54 .BR strtok_r ():
  55 _SVID_SOURCE || _BSD_SOURCE || _POSIX_C_SOURCE\ >=\ 1 ||
  56 _XOPEN_SOURCE || _POSIX_SOURCE
  57 .ad b
  58 .SH 説明
  59 .BR strtok ()
  60 関数は文字列を解析してトークンに分割する。
  61 .BR strtok ()
  62 を最初に呼び出す際には、解析対象の文字列を \fIstr\fP に
  63 指定する。同じ文字列の解析を行うその後の呼び出しでは、
  64 \fIstr\fP には NULL を指定する。
  65
  66 \fIdelim\fP 引き数には、解析する文字列をトークンに区切る文字集合を
  67 指定する。同じ文字列を解析する一連の呼び出しにおいて、
  68 \fIdelim\fP に違う文字列を指定してもよい。
  69
  70 .BR strtok ()
  71 のそれぞれの呼び出しでは、次のトークンを
  72 格納した NULL 終端された文字列へのポインタが返される。
  73 この文字列には区切り文字は含まれない。
  74 これ以上トークンが見つからなかった場合には、NULL が返される。
  75
  76 解析対象の文字列に2つ以上の区切り文字が連続している場合には、
  77 一つの区切り文字とみなされる。
  78 文字列の先頭や末尾にある区切り文字は無視される。言い換えると、
  79 .BR strtok ()
  80 が返すトークンは常に空でない文字列となる。
  81
  82 .BR strtok_r ()
  83 関数は
  84 .BR strtok ()
  85 のリエントラント版である。
  86 \fIsaveptr\fP 引き数は \fIchar *\fP 変数へのポインタであり、
  87 同じ文字列の解析を行う
  88 .BR strtok_r ()
  89 の呼び出し間で処理状況を保存するために
  90 .BR strtok_r ()
  91 内部で使用される。
  92
  93 .BR strtok_r ()
  94 を最初に呼び出す際には、
  95 .I str
  96 は解析対象の文字列を指していなければならず、
  97 .I saveptr
  98 の値は無視される。それ以降の呼び出しでは、
  99 .I str
 100 は NULL とし、
 101 .I saveptr
 102 は前回の呼び出し以降変更しないようにしなければならない。
 103
 104 .BR strtok_r ()
 105 の呼び出し時に異なる \fIsaveptr\fP 引き数を指定することで、
 106 異なる文字列の解析を同時に行うことができる。
 107 .SH 返り値
 108 .BR strtok ()
 109 と
 110 .BR strtok_r ()
 111 は次のトークンへのポインタか、
 112 トークンがなければ NULL を返す。
 113 .SH 準拠
 114 .TP
 115 .BR strtok ()
 116 SVr4, POSIX.1-2001, 4.3BSD, C89, C99.
 117 .TP
 118 .BR strtok_r ()
 119 POSIX.1-2001.
 120 .SH バグ
 121 これらの関数を使うのは慎重に吟味すること。
 122 使用する場合は、以下の点に注意が必要である。
 123 .IP * 2
 124 これらの関数はその最初の引数を変更する。
 125 .IP *
 126 これらの関数は const な文字列では使えない。
 127 .IP *
 128 区切り文字自体は失われてしまう。
 129 .IP *
 130 .BR strtok ()
 131 関数は文字列の解析に静的バッファを用いるので、スレッドセーフでない。
 132 これが問題になる場合は
 133 .BR strtok_r ()
 134 を用いること。
 135 .SH 例
 136 以下のプログラムは、
 137 .BR strtok_r ()
 138 を利用するループを入れ子にして使用し、
 139 文字列を2階層のトークンに分割するものである。
 140 1番目のコマンドライン引き数には、解析対象の文字列を指定する。
 141 2番目の引き数には、文字列を「大きな」トークンに分割するために
 142 使用する区切り文字を指定する。
 143 3番目の引き数には、「大きな」トークンを細かく分割するために
 144 使用する区切り文字を指定する。
 145 .PP
 146 .PP
 147 このプログラムの出力例を以下に示す。
 148 .PP
 149 .in +4n
 150 .nf
 151 .RB "$" " ./a.out \(aqa/bbb///cc;xxx:yyy:\(aq \(aq:;\(aq \(aq/\(aq"
 152 1: a/bbb///cc
 153          \-\-> a
 154          \-\-> bbb
 155          \-\-> cc
 156 2: xxx
 157          \-\-> xxx
 158 3: yyy
 159          \-\-> yyy
 160 .fi
 161 .in
 162 .SS プログラムのソース
 163 \&
 164 .nf
 165 #include <stdio.h>
 166 #include <stdlib.h>
 167 #include <string.h>
 168
 169 int
 170 main(int argc, char *argv[])
 171 {
 172     char *str1, *str2, *token, *subtoken;
 173     char *saveptr1, *saveptr2;
 174     int j;
 175
 176     if (argc != 4) {
 177         fprintf(stderr, "Usage: %s string delim subdelim\\n",
 178                 argv[0]);
 179         exit(EXIT_FAILURE);
 180     }
 181
 182     for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
 183         token = strtok_r(str1, argv[2], &saveptr1);
 184         if (token == NULL)
 185             break;
 186         printf("%d: %s\\n", j, token);
 187
 188         for (str2 = token; ; str2 = NULL) {
 189             subtoken = strtok_r(str2, argv[3], &saveptr2);
 190             if (subtoken == NULL)
 191                 break;
 192             printf("\t \-\-> %s\\n", subtoken);
 193         }
 194     }
 195
 196     exit(EXIT_SUCCESS);
 197 }
 198 .fi
 199 .PP
 200 .BR strtok ()
 201 を使った別のプログラム例が
 202 .BR getaddrinfo_a (3)
 203 にある。
 204 .SH 関連項目
 205 .BR index (3),
 206 .BR memchr (3),
 207 .BR rindex (3),
 208 .BR strchr (3),
 209 .BR string (3),
 210 .BR strpbrk (3),
 211 .BR strsep (3),
 212 .BR strspn (3),
 213 .BR strstr (3),
 214 .BR wcstok (3)