draft/man3/hash.3

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)hash.3      8.6 (Berkeley) 8/18/94
  33 .\"
  34 .\" Japanese Version Copyright (c) 1999 Shouichi Saito
  35 .\"     all rights reserved.
  36 .\" Translated Mon Jul 26 14:22:49 JST 1999
  37 .\"     by Shouichi Saito <ss236rx@ymg.urban.ne.jp>
  38 .\" Proofed Tue Aug 17 1999 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
  39 .\" Updated 2008-02-10, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.77
  40 .\"
  41 .\"WORD:        access method           アクセスメソッド
  42 .\"WORD:        bucket                  バケット
  43 .\"
  44 .TH HASH 3 1994-08-18 "" "Linux Programmer's Manual"
  45 .UC 7
  46 .SH 名前
  47 .\"O hash \- hash database access method
  48 hash \- hash データベースへのアクセスメソッド
  49 .SH 書式
  50 .nf
  51 .ft B
  52 #include <sys/types.h>
  53 #include <db.h>
  54 .ft R
  55 .fi
  56 .SH 説明
  57 .\"O The routine
  58 .\"O .BR dbopen (3)
  59 .\"O is the library interface to database files.
  60 .\"O One of the supported file formats is hash files.
  61 ルーチン
  62 .BR dbopen (3)
  63 はデータベースファイルに対するライブラリインターフェースである。
  64 サポートされているファイルフォーマットのひとつに hash ファイルがある。
  65 .\"O The general description of the database access methods is in
  66 .\"O .BR dbopen (3),
  67 .\"O this manual page describes only the hash specific information.
  68 データベースへのアクセスメソッドに関する一般的な記述は
  69 .BR dbopen (3)
  70 に書かれている。
  71 このマニュアルページでは hash 特有の情報についてのみ記述する。
  72 .PP
  73 .\"O The hash data structure is an extensible, dynamic hashing scheme.
  74 hash データ構造は、拡張可能な動的ハッシュスキームである。
  75 .PP
  76 .\"O The access method specific data structure provided to
  77 .\"O .BR dbopen (3)
  78 .\"O is defined in the
  79 .\"O .I <db.h>
  80 .\"O include file as follows:
  81 .BR dbopen (3)
  82 に渡される hash アクセスメソッドに特有のデータ構造体は、
  83 .I <db.h>
  84 インクルードファイルで以下のように定義されている。
  85 .in +4n
  86 .nf
  87
  88 typedef struct {
  89     unsigned int       bsize;
  90     unsigned int       ffactor;
  91     unsigned int       nelem;
  92     unsigned int       cachesize;
  93     uint32_t         (*hash)(const void *, size_t);
  94     int         lorder;
  95 } HASHINFO;
  96 .fi
  97 .in
  98 .PP
  99 .\"O The elements of this structure are as follows:
 100 この構造体の要素を以下に示す。
 101 .TP 10
 102 .I bsize
 103 .\"O defines the hash table bucket size, and is, by default, 256 bytes.
 104 .\"O It may be preferable to increase the page size for disk-resident tables
 105 .\"O and tables with large data items.
 106 hash テーブルバケット (table bucket) のサイズを定義する。
 107 デフォルトは 256 バイトである。
 108 ディスクに置かれるテーブルやデータアイテムが大きいテーブルでは
 109 ページサイズを大きくするほうが良いだろう。
 110 .TP
 111 .I ffactor
 112 .\"O indicates a desired density within the hash table.
 113 .\"O It is an approximation of the number of keys allowed to accumulate in any
 114 .\"O one bucket, determining when the hash table grows or shrinks.
 115 .\"O The default value is 8.
 116 ユーザが望む hash テーブル中の密度である。
 117 これはそれぞれのバケットに格納できるキーの概数であり、
 118 hash テーブルを拡大・縮小を作用する。
 119 デフォルトは 8 である。
 120 .TP
 121 .I nelem
 122 .\"O is an estimate of the final size of the hash table.
 123 .\"O If not set or set too low, hash tables will expand gracefully as keys
 124 .\"O are entered, although a slight performance degradation may be noticed.
 125 .\"O The default value is 1.
 126 hash テーブルの最終サイズを大まかに見積もった値である。
 127 この値がセットされていなかったり、あまりに低くセットされていると、
 128 hash テーブルはキーが入ってくるに応じて拡張される。
 129 しかし少しパフォーマンスが (おそらく気付く程度に) 落ちる。
 130 デフォルト値は 1 である。
 131 .TP
 132 .I cachesize
 133 .\"O is the suggested maximum size, in bytes, of the memory cache.
 134 .\"O This value is
 135 .\"O .IR "only advisory" ,
 136 .\"O and the access method will allocate more memory rather than fail.
 137 メモリキャッシュの最大値 (バイト単位) の参考値。
 138 この値は
 139 .BR あくまで参考であり 、
 140 アクセスメソッドはこの値を越えたメモリの割り当てに成功することもある。
 141 .TP
 142 .I hash
 143 .\"O is a user-defined hash function.
 144 .\"O Since no hash function performs equally well on all possible data, the
 145 .\"O user may find that the built-in hash function does poorly on a particular
 146 .\"O data set.
 147 はユーザー定義の hash 関数である。
 148 全てのデータに対してうまく作用する hash 関数と言うのはないから、
 149 特定のデータセットに対しては組み込みの hash 関数では
 150 パフォーマンスが低いこともあるかもしれない。
 151 .\"O A user-specified hash functions must take two arguments (a pointer to a byte
 152 .\"O string and a length) and return a 32-bit quantity to be used as the hash
 153 .\"O value.
 154 ユーザー定義の hash 関数は二つの引数をとらなくてはならない (バイト文字
 155 列へのポインタと、長さ)。
 156 そして hash 値として使われる 32ビットの値を返さなくてはならない。
 157 .TP
 158 .I lorder
 159 .\"O is the byte order for integers in the stored database metadata.
 160 .\"O The number should represent the order as an integer; for example,
 161 .\"O big endian order would be the number 4,321.
 162 データベースに格納されているメタデータの整数値のバイトオーダー。
 163 この数字は、順序を整数で表したものである。
 164 例えばビッグエンディアンなら、この数値は 4,321 となる。
 165 .\"O If
 166 .I lorder
 167 .\"O is 0 (no order is specified) the current host order is used.
 168 .\"O If the file already exists, the specified value is ignored and the
 169 .\"O value specified when the tree was created is used.
 170 が 0 (指定されていない)場合、現在のホスト
 171 で使われている並び順が使われる。
 172 ファイルが既に存在する場合、指定した値は無視されツリーが作られ
 173 た時に指定されていた値が使われる。
 174 .PP
 175 .\"O If the file already exists (and the
 176 .\"O .B O_TRUNC
 177 .\"O flag is not specified), the
 178 .\"O values specified for
 179 .\"O .IR bsize ,
 180 .\"O .IR ffactor ,
 181 .\"O .IR lorder ,
 182 .\"O and
 183 .\"O .I nelem
 184 .\"O are
 185 .\"O ignored and the values specified when the tree was created are used.
 186 .\"NAKANO the tree → the hash, でしょう.
 187 ファイルが既に存在している (または
 188 .B O_TRUNC
 189 フラグが指定されていない) と、
 190 .IR bsize ,
 191 .IR ffactor ,
 192 .IR lorder ,
 193 .I nelem
 194 に指定された値は無視され、
 195 ハッシュが作られた時に使った値が使われる。
 196 .PP
 197 .\"O If a hash function is specified,
 198 hash 関数が指定されると、
 199 .I hash_open
 200 .\"O will attempt to determine if the hash function specified is the same as
 201 .\"O the one with which the database was created, and will fail if it is not.
 202 はデータベースが作られた時に指定されていた
 203 hash 関数と今回指定された hash 関数が同じかどうかを調べ、
 204 同じでない場合には失敗する。
 205 .PP
 206 .\"O Backward-compatible interfaces to the routines described in
 207 .BR dbm (3),
 208 と
 209 .\"O and
 210 .BR ndbm (3)
 211 に記述されているルーチンへの過去互換を取るためのインターフェイスが
 212 存在する。しかしこれらのインターフェイスは以前のファイルフォー
 213 マットとは互換性がない。
 214 .\"O are provided, however these interfaces are not compatible with
 215 .\"O previous file formats.
 216 .SH エラー
 217 .\"O The
 218 .\"O .I hash
 219 .\"O access method routines may fail and set
 220 .\"O .I errno
 221 .\"O for any of the errors specified for the library routine
 222 .\"O .BR dbopen (3).
 223 .I hash
 224 アクセスメソッドルーチンは、失敗するとライブラリルーチン
 225 .BR dbopen (3)
 226 で指定されているエラーに応じた
 227 .I errno
 228 をセットする。
 229 .SH バグ
 230 .\"O Only big and little endian byte order are supported.
 231 バイトオーダーとしてはビッグエンディアンとリトルエンディアンのみが
 232 サポートされている。
 233 .SH 関連項目
 234 .BR btree (3),
 235 .BR dbopen (3),
 236 .BR mpool (3),
 237 .BR recno (3)
 238 .sp
 239 .IR "Dynamic Hash Tables" ,
 240 Per-Ake Larson, Communications of the ACM, April 1988.
 241 .sp
 242 .IR "A New Hash Package for UNIX" ,
 243 Margo Seltzer, USENIX Proceedings, Winter 1991.