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 The \fBstrtok\fP()  function breaks a string into a sequence of zero or more
  59 nonempty tokens.  On the first call to \fBstrtok\fP()  the string to be parsed
  60 should be specified in \fIstr\fP.  In each subsequent call that should parse
  61 the same string, \fIstr\fP must be NULL.
  62
  63 \fIdelim\fP 引き数には、解析対象の文字列をトークンに区切るのに使用する
  64 バイト集合を指定する。同じ文字列を解析する一連の呼び出しにおいて、
  65 \fIdelim\fP に違う文字列を指定してもよい。
  66
  67 \fBstrtok\fP() のそれぞれの呼び出しでは、次のトークンを格納した NULL 終端
  68 された文字列へのポインタが返される。この文字列には区切りバイトは含まれ
  69 ない。これ以上トークンが見つからなかった場合には、NULL が返される。
  70
  71 A sequence of calls to \fBstrtok\fP()  that operate on the same string
  72 maintains a pointer that determines the point from which to start searching
  73 for the next token.  The first call to \fBstrtok\fP()  sets this pointer to
  74 point to the first byte of the string.  The start of the next token is
  75 determined by scanning forward for the next nondelimiter byte in \fIstr\fP.  If
  76 such a byte is found, it is taken as the start of the next token.  If no
  77 such byte is found, then there are no more tokens, and \fBstrtok\fP()  returns
  78 NULL.  (A string that is empty or that contains only delimiters will thus
  79 cause \fBstrtok\fP()  to return NULL on the first call.)
  80
  81 The end of each token is found by scanning forward until either the next
  82 delimiter byte is found or until the terminating null byte (\(aq\e0\(aq) is
  83 encountered.  If a delimiter byte is found, it is overwritten with a null
  84 byte to terminate the current token, and \fBstrtok\fP()  saves a pointer to the
  85 following byte; that pointer will be used as the starting point when
  86 searching for the next token.  In this case, \fBstrtok\fP()  returns a pointer
  87 to the start of the found token.
  88
  89 From the above description, it follows that a sequence of two or more
  90 contiguous delimiter bytes in the parsed string is considered to be a single
  91 delimiter, and that delimiter bytes at the start or end of the string are
  92 ignored.  Put another way: the tokens returned by \fBstrtok\fP()  are always
  93 nonempty strings.  Thus, for example, given the string "\fIaaa;;bbb,\fP",
  94 successive calls to \fBstrtok\fP()  that specify the delimiter string "\fI;,\fP"
  95 would return the strings "\fIaaa\fP" and "\fIbbb\fP", and then a NULL pointer.
  96
  97 The \fBstrtok_r\fP()  function is a reentrant version \fBstrtok\fP().  The
  98 \fIsaveptr\fP argument is a pointer to a \fIchar\ *\fP variable that is used
  99 internally by \fBstrtok_r\fP()  in order to maintain context between successive
 100 calls that parse the same string.
 101
 102 \fBstrtok_r\fP()  を最初に呼び出す際には、 \fIstr\fP は解析対象の文字列を指していなければならず、 \fIsaveptr\fP
 103 の値は無視される。それ以降の呼び出しでは、 \fIstr\fP は NULL とし、 \fIsaveptr\fP
 104 は前回の呼び出し以降変更しないようにしなければならない。
 105
 106 \fBstrtok_r\fP()  の呼び出し時に異なる \fIsaveptr\fP 引き数を指定することで、 異なる文字列の解析を同時に行うことができる。
 107 .SH 返り値
 108 \fBstrtok\fP()  と \fBstrtok_r\fP()  は次のトークンへのポインタか、 トークンがなければ NULL を返す。
 109 .SH ATTRIBUTES
 110 .SS "Multithreading (see pthreads(7))"
 111 The \fBstrtok\fP()  function is not thread\-safe.
 112 .LP
 113 The \fBstrtok_r\fP()  function is thread\-safe.
 114 .SH 準拠
 115 .TP
 116 \fBstrtok\fP()
 117 SVr4, POSIX.1\-2001, 4.3BSD, C89, C99.
 118 .TP
 119 \fBstrtok_r\fP()
 120 POSIX.1\-2001.
 121 .SH バグ
 122 これらの関数を使うのは慎重に吟味すること。 使用する場合は、以下の点に注意が必要である。
 123 .IP * 2
 124 これらの関数はその最初の引数を変更する。
 125 .IP *
 126 これらの関数は const な文字列では使えない。
 127 .IP *
 128 区切りバイト自体は失われてしまう。
 129 .IP *
 130 \fBstrtok\fP()  関数は文字列の解析に静的バッファを用いるので、スレッドセーフでない。 これが問題になる場合は \fBstrtok_r\fP()
 131 を用いること。
 132 .SH 例
 133 以下のプログラムは、 \fBstrtok_r\fP() を利用するループを入れ子にして使用し、
 134 文字列を 2 階層のトークンに分割するものである。 1番目のコマンドライン
 135 引き数には、解析対象の文字列を指定する。 2 番目の引き数には、文字列を
 136 「大きな」トークンに分割するために 使用する区切りバイトを指定する。
 137 3 番目の引き数には、「大きな」トークンを細かく分割するために使用する
 138 区切りバイトを指定する。
 139 .PP
 140 このプログラムの出力例を以下に示す。
 141 .PP
 142 .in +4n
 143 .nf
 144 $\fB ./a.out \(aqa/bbb///cc;xxx:yyy:\(aq \(aq:;\(aq \(aq/\(aq\fP
 145 1: a/bbb///cc
 146          \-\-> a
 147          \-\-> bbb
 148          \-\-> cc
 149 2: xxx
 150          \-\-> xxx
 151 3: yyy
 152          \-\-> yyy
 153 .fi
 154 .in
 155 .SS プログラムのソース
 156 \&
 157 .nf
 158 #include <stdio.h>
 159 #include <stdlib.h>
 160 #include <string.h>
 161
 162 int
 163 main(int argc, char *argv[])
 164 {
 165     char *str1, *str2, *token, *subtoken;
 166     char *saveptr1, *saveptr2;
 167     int j;
 168
 169     if (argc != 4) {
 170         fprintf(stderr, "Usage: %s string delim subdelim\en",
 171                 argv[0]);
 172         exit(EXIT_FAILURE);
 173     }
 174
 175     for (j = 1, str1 = argv[1]; ; j++, str1 = NULL) {
 176         token = strtok_r(str1, argv[2], &saveptr1);
 177         if (token == NULL)
 178             break;
 179         printf("%d: %s\en", j, token);
 180
 181         for (str2 = token; ; str2 = NULL) {
 182             subtoken = strtok_r(str2, argv[3], &saveptr2);
 183             if (subtoken == NULL)
 184                 break;
 185             printf("\t \-\-> %s\en", subtoken);
 186         }
 187     }
 188
 189     exit(EXIT_SUCCESS);
 190 }
 191 .fi
 192 .PP
 193 \fBstrtok\fP()  を使った別のプログラム例が \fBgetaddrinfo_a\fP(3)  にある。
 194 .SH 関連項目
 195 \fBindex\fP(3), \fBmemchr\fP(3), \fBrindex\fP(3), \fBstrchr\fP(3), \fBstring\fP(3),
 196 \fBstrpbrk\fP(3), \fBstrsep\fP(3), \fBstrspn\fP(3), \fBstrstr\fP(3), \fBwcstok\fP(3)
 197 .SH この文書について
 198 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 199 である。プロジェクトの説明とバグ報告に関する情報は
 200 http://www.kernel.org/doc/man\-pages/ に書かれている。