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 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Rewritten old page, 960210, aeb@cwi.nl
  27 .\" Updated, added strtok_r. 2000-02-13 Nicolás Lichtmaier <nick@debian.org>
  28 .\" 2005-11-17, mtk: Substantial parts rewritten
  29 .\"
  30 .\"*******************************************************************
  31 .\"
  32 .\" This file was generated with po4a. Translate the source file.
  33 .\"
  34 .\"*******************************************************************
  35 .TH STRTOK 3 2012\-05\-10 GNU "Linux Programmer's Manual"
  36 .SH 名前
  37 strtok, strtok_r \- 文字列からトークンを取り出す
  38 .SH 書式
  39 .nf
  40 \fB#include <string.h>\fP
  41 .sp
  42 \fBchar *strtok(char *\fP\fIstr\fP\fB, const char *\fP\fIdelim\fP\fB);\fP
  43 .sp
  44 \fBchar *strtok_r(char *\fP\fIstr\fP\fB, const char *\fP\fIdelim\fP\fB, char **\fP\fIsaveptr\fP\fB);\fP
  45 .fi
  46 .sp
  47 .in -4n
  48 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  49 .in
  50 .sp
  51 .ad l
  52 \fBstrtok_r\fP(): _SVID_SOURCE || _BSD_SOURCE || _POSIX_C_SOURCE\ >=\ 1 ||
  53 _XOPEN_SOURCE || _POSIX_SOURCE
  54 .ad b
  55 .SH 説明
  56 \fBstrtok\fP()  関数は文字列を解析してトークンに分割する。 \fBstrtok\fP()  を最初に呼び出す際には、解析対象の文字列を \fIstr\fP
  57 に 指定する。同じ文字列の解析を行うその後の呼び出しでは、 \fIstr\fP には NULL を指定する。
  58
  59 \fIdelim\fP 引き数には、解析対象の文字列をトークンに区切るのに使用する
  60 バイト集合を指定する。同じ文字列を解析する一連の呼び出しにおいて、
  61 \fIdelim\fP に違う文字列を指定してもよい。
  62
  63 \fBstrtok\fP() のそれぞれの呼び出しでは、次のトークンを格納した NULL 終端
  64 された文字列へのポインタが返される。この文字列には区切りバイトは含まれ
  65 ない。これ以上トークンが見つからなかった場合には、NULL が返される。
  66
  67 解析対象の文字列に 2 つ以上の区切りバイトが連続している場合には、
  68 一つの区切りバイトとみなされる。 文字列の先頭や末尾にある区切りバイトは
  69 無視される。言い換えると、 \fBstrtok\fP() が返すトークンは必ず空でない
  70 文字列となる。
  71
  72 \fBstrtok_r\fP()  関数は \fBstrtok\fP()  のリエントラント版である。 \fIsaveptr\fP 引き数は \fIchar *\fP
  73 変数へのポインタであり、 同じ文字列の解析を行う \fBstrtok_r\fP()  の呼び出し間で処理状況を保存するために \fBstrtok_r\fP()
  74 内部で使用される。
  75
  76 \fBstrtok_r\fP()  を最初に呼び出す際には、 \fIstr\fP は解析対象の文字列を指していなければならず、 \fIsaveptr\fP
  77 の値は無視される。それ以降の呼び出しでは、 \fIstr\fP は NULL とし、 \fIsaveptr\fP
  78 は前回の呼び出し以降変更しないようにしなければならない。
  79
  80 \fBstrtok_r\fP()  の呼び出し時に異なる \fIsaveptr\fP 引き数を指定することで、 異なる文字列の解析を同時に行うことができる。
  81 .SH 返り値
  82 \fBstrtok\fP()  と \fBstrtok_r\fP()  は次のトークンへのポインタか、 トークンがなければ NULL を返す。
  83 .SH 準拠
  84 .TP
  85 \fBstrtok\fP()
  86 SVr4, POSIX.1\-2001, 4.3BSD, C89, C99.
  87 .TP
  88 \fBstrtok_r\fP()
  89 POSIX.1\-2001.
  90 .SH バグ
  91 これらの関数を使うのは慎重に吟味すること。 使用する場合は、以下の点に注意が必要である。
  92 .IP * 2
  93 これらの関数はその最初の引数を変更する。
  94 .IP *
  95 これらの関数は const な文字列では使えない。
  96 .IP *
  97 区切りバイト自体は失われてしまう。
  98 .IP *
  99 \fBstrtok\fP()  関数は文字列の解析に静的バッファを用いるので、スレッドセーフでない。 これが問題になる場合は \fBstrtok_r\fP()
 100 を用いること。
 101 .SH 例
 102 以下のプログラムは、 \fBstrtok_r\fP() を利用するループを入れ子にして使用し、
 103 文字列を 2 階層のトークンに分割するものである。 1番目のコマンドライン
 104 引き数には、解析対象の文字列を指定する。 2 番目の引き数には、文字列を
 105 「大きな」トークンに分割するために 使用する区切りバイトを指定する。
 106 3 番目の引き数には、「大きな」トークンを細かく分割するために使用する
 107 区切りバイトを指定する。
 108 .PP
 109 このプログラムの出力例を以下に示す。
 110 .PP
 111 .in +4n
 112 .nf
 113 $\fB ./a.out \(aqa/bbb///cc;xxx:yyy:\(aq \(aq:;\(aq \(aq/\(aq\fP
 114 1: a/bbb///cc
 115          \-\-> a
 116          \-\-> bbb
 117          \-\-> cc
 118 2: xxx
 119          \-\-> xxx
 120 3: yyy
 121          \-\-> yyy
 122 .fi
 123 .in
 124 .SS プログラムのソース
 125 \&
 126 .nf
 127 #include <stdio.h>
 128 #include <stdlib.h>
 129 #include <string.h>
 130
 131 int
 132 main(int argc, char *argv[])
 133 {
 134     char *str1, *str2, *token, *subtoken;
 135     char *saveptr1, *saveptr2;
 136     int j;
 137
 138     if (argc != 4) {
 139         fprintf(stderr, "Usage: %s string delim subdelim\en",
 140                 argv[0]);
 141         exit(EXIT_FAILURE);
 142     }
 143
 144     for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
 145         token = strtok_r(str1, argv[2], &saveptr1);
 146         if (token == NULL)
 147             break;
 148         printf("%d: %s\en", j, token);
 149
 150         for (str2 = token; ; str2 = NULL) {
 151             subtoken = strtok_r(str2, argv[3], &saveptr2);
 152             if (subtoken == NULL)
 153                 break;
 154             printf("\t \-\-> %s\en", subtoken);
 155         }
 156     }
 157
 158     exit(EXIT_SUCCESS);
 159 }
 160 .fi
 161 .PP
 162 \fBstrtok\fP()  を使った別のプログラム例が \fBgetaddrinfo_a\fP(3)  にある。
 163 .SH 関連項目
 164 \fBindex\fP(3), \fBmemchr\fP(3), \fBrindex\fP(3), \fBstrchr\fP(3), \fBstring\fP(3),
 165 \fBstrpbrk\fP(3), \fBstrsep\fP(3), \fBstrspn\fP(3), \fBstrstr\fP(3), \fBwcstok\fP(3)
 166 .SH この文書について
 167 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.51 の一部
 168 である。プロジェクトの説明とバグ報告に関する情報は
 169 http://www.kernel.org/doc/man\-pages/ に書かれている。