draft/man3/argz_add.3

   1 .\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\" Distributed under GPL
   3 .\" based on the description in glibc source and infopages
   4 .\"
   5 .\" Corrections and additions, aeb
   6 .\"*******************************************************************
   7 .\"
   8 .\" This file was generated with po4a. Translate the source file.
   9 .\"
  10 .\"*******************************************************************
  11 .TH ARGZ_ADD 3 2007\-05\-18 "" "Linux Programmer's Manual"
  12 .SH 名前
  13 argz_add, argz_add_sep, argz_append, argz_count, argz_create,
  14 argz_create_sep, argz_delete, argz_extract, argz_insert, argz_next,
  15 argz_replace, argz_stringify \- argz リストを操作するための関数群
  16 .SH 書式
  17 .nf
  18 \fB#include <argz.h>\fP
  19 .sp
  20 \fBerror_t argz_add(char **\fP\fIargz\fP\fB, size_t *\fP\fIargz_len\fP\fB, const char *\fP\fIstr\fP\fB);\fP
  21 .sp
  22 \fBerror_t argz_add_sep(char **\fP\fIargz\fP\fB, size_t *\fP\fIargz_len\fP\fB,\fP
  23 .ti 20n
  24 \fBconst char *\fP\fIstr\fP\fB, int \fP\fIdelim\fP\fB);\fP
  25 .sp
  26 \fBerror_t argz_append(char **\fP\fIargz\fP\fB, size_t *\fP\fIargz_len\fP\fB,\fP
  27 .ti 20n
  28 \fBconst char *\fP\fIbuf\fP\fB, size_t \fP\fIbuf_len\fP\fB);\fP
  29 .sp
  30 \fBsize_t argz_count(const char *\fP\fIargz\fP\fB, size_t \fP\fIargz_len\fP\fB);\fP
  31 .sp
  32 \fBerror_t argz_create(char * const \fP\fIargv\fP\fB[], char **\fP\fIargz\fP\fB,\fP
  33 .ti 20n
  34 \fBsize_t *\fP\fIargz_len\fP\fB);\fP
  35 .sp
  36 \fBerror_t argz_create_sep(const char *\fP\fIstr\fP\fB, int \fP\fIsep\fP\fB, char **\fP\fIargz\fP\fB,\fP
  37 .ti 20n
  38 \fBsize_t *\fP\fIargz_len\fP\fB);\fP
  39 .sp
  40 \fBerror_t argz_delete(char **\fP\fIargz\fP\fB, size_t *\fP\fIargz_len\fP\fB, char *\fP\fIentry\fP\fB);\fP
  41 .sp
  42 \fBvoid argz_extract(char *\fP\fIargz\fP\fB, size_t \fP\fIargz_len\fP\fB, char  **\fP\fIargv\fP\fB);\fP
  43 .sp
  44 \fBerror_t argz_insert(char **\fP\fIargz\fP\fB, size_t *\fP\fIargz_len\fP\fB, char *\fP\fIbefore\fP\fB,\fP
  45 .ti 20n
  46 \fBconst char *\fP\fIentry\fP\fB);\fP
  47 .sp
  48 \fBchar *argz_next(char *\fP\fIargz\fP\fB, size_t \fP\fIargz_len\fP\fB, const char *\fP\fIentry\fP\fB);\fP
  49 .sp
  50 \fBerror_t argz_replace(char **\fP\fIargz\fP\fB, size_t *\fP\fIargz_len\fP\fB, const char *\fP\fIstr\fP\fB,\fP
  51 .ti 20n
  52 \fBconst char *\fP\fIwith\fP\fB, unsigned int *\fP\fIreplace_count\fP\fB);\fP
  53 .sp
  54 \fBvoid argz_stringify(char *\fP\fIargz\fP\fB, size_t \fP\fIlen\fP\fB, int \fP\fIsep\fP\fB);\fP
  55 .fi
  56 .SH 説明
  57 これらの関数は glibc 固有である。
  58 .LP
  59 argz vector は長さ情報付きの文字バッファへのポインタである。 文字バッファでは、複数の文字列が NULL バイト
  60 (\e(aq\e0\e(aq) で区切られており、 文字列の配列として解釈されるようになっている。 長さが 0 でない場合、バッファの最後のバイトは
  61 NULL バイトでなければならない。
  62 .LP
  63 これらの関数は argz vector を操作するためのものである。 ペア (NULL,0) は argz vector であり、逆に言えば 長さ 0
  64 の argz vectorは NULL ポインタを持たなければならない。 空でない argz vector の割り当ては \fBmalloc\fP(3)
  65 を使って行われる。したがって、argz vector を解放するのに \fBfree\fP(3)  を使うことができる。
  66 .LP
  67 \fBargz_add\fP()  は、文字列 \fIstr\fP を配列 \fI*argz\fP の末尾に追加し、 \fI*argz\fP と \fI*argz_len\fP
  68 を更新する。
  69 .LP
  70 \fBargz_add_sep\fP()  も同様の動作をするが、区切り文字 \fIdelim\fP にしたがって文字列 \fIstr\fP
  71 を複数の文字列に分割する点が異なる。 例えば、区切り文字 \e(aq:\e(aq を指定して、UNIX サーチ・パスに対して
  72 この関数を使うことができるだろう。
  73 .LP
  74 \fBargz_append\fP()  は argz vector (\fIbuf\fP,\ \fIbuf_len\fP)  の後ろに (*\fIargz\fP,\ \fI*argz_len\fP)  を付け加え、 \fI*argz\fP と \fI*argz_len\fP を更新する。 (したがって、 \fI*argz_len\fP は
  75 \fIbuf_len\fP だけ増加する。)
  76 .LP
  77 \fBargz_count\fP()  は (\fIargz\fP,\ \fIargz_len\fP)  内の文字列の数を数える。実際には NULL バイト
  78 (\e(aq\e0\e(aq) の数を数えている。
  79 .LP
  80 \fBargz_create\fP()  は、UNIX 流の引き数ベクトルである (\fI(char *) 0\fP で終端される)  \fIargv\fP を、argz
  81 vector (\fI*argz\fP,\ \fI*argz_len\fP)  に変換する。
  82 .LP
  83 \fBargz_create_sep\fP()  は、NULL 終端された文字列 \fIstr\fP を区切り文字 \fIsep\fP が現れる毎に分割しながら、argz
  84 vector (*\fIargz\fP,\ \fI*argz_len\fP)  に変換する。
  85 .LP
  86 \fBargz_delete\fP()  は、 \fIentry\fP で指し示された文字列を argz vector (\fI*argz\fP,\ \fI*argz_len\fP)  から削除し、 \fI*argz\fP と \fI*argz_len\fP を更新する。
  87 .LP
  88 \fBargz_extract\fP()  は \fBargz_create\fP()  の反対の操作を行う。argz vector (\fIargz\fP,\ \fIargz_len\fP)  を調べ、 \fIargv\fP から始まる配列をサブ文字列へのポインタで埋めていき、 一番最後に NULL を入れて、UNIX
  89 流の argv ベクトルを作成する。 配列 \fIargv\fP は \fIargz_count\fP(\fIargz\fP,\fIargz_len\fP) + 1
  90 個のポインタを収容できる空間を持っていなければならない。
  91 .LP
  92 \fBargz_insert\fP()  は \fBargz_delete\fP()  の反対の操作を行う。argz vector (\fI*argz\fP,\ \fI*argz_len\fP)  の位置 \fIbefore\fP に引き数 \fIentry\fP を挿入し、 \fI*argz\fP と \fI*argz_len\fP
  93 を更新する。 \fIbefore\fP が NULL の場合、 \fIentry\fP は末尾に挿入される。
  94 .LP
  95 \fBargz_next\fP()  は argz vector を順番に調べるための関数である。 \fIentry\fP が NULL
  96 の場合、最初のエントリを返す。 そうでない場合、次のエントリを返す。 次のエントリがない場合、NULL を返す。
  97 .LP
  98 \fBargz_replace\fP()  は、 \fIstr\fP をすべて \fIwith\fP で置き換える (必要に応じて argz の再割り当てを行う)。
  99 \fIreplace_count\fP が NULL でない場合、 \fI*replace_count\fP を置き換えを行った数だけ増やす。
 100 .LP
 101 \fBargz_stringify\fP()  は \fBargz_create_sep\fP()  の反対の操作を行う。 末尾の NULL バイト以外の全ての
 102 NULL バイト (\e(aq\e0\e(aq) を \fIsep\fP で置き換えて、 argz vector を通常の文字列に変換する。
 103 .SH 返り値
 104 メモリ割り当てを行う argz 関数群はすべて \fIerror_t\fP 型の返り値を持つ。 成功した場合は 0 を返し、割り当てエラーが発生した場合は
 105 \fBENOMEM\fP を返す。
 106 .SH 準拠
 107 これらの関数は GNU による拡張である。注意して使用すること。
 108 .SH バグ
 109 NULL バイトで終端されていない argz vector を使用した場合、 segmentation fault を起こすかもしれない。
 110 .SH 関連項目
 111 \fBenvz_add\fP(3)