draft/man3/mpool.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 .\"     @(#)mpool.3     8.1 (Berkeley) 6/4/93
  33 .\"
  34 .\" Japanese Version Copyright (c) 1999 Shouichi Saito
  35 .\"     all rights reserved.
  36 .\" Translated Mon Jul 26 21:51:36 JST 1999
  37 .\"     by Shouichi Saito <ss236rx@ymg.urban.ne.jp>
  38 .\" Proofed Tue Aug 19 1999 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
  39 .\"
  40 .\"WORD:        descriptor      デスクリプタ
  41 .TH MPOOL 3 1993-06-04 "" "Linux Programmer's Manual"
  42 .UC 7
  43 .SH 名前
  44 .\"O  mpool \- shared memory buffer pool
  45 mpool \- 共有メモリバッファプール
  46 .SH 書式
  47 .nf
  48 .B #include <db.h>
  49 .B #include <mpool.h>
  50 .sp
  51 .BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \
  52 ", pgno_t " maxcache );
  53 .sp
  54 .BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *),"
  55 .BI "                  void (*" pgout ")(void *, pgno_t, void *),"
  56 .BI "                  void *" pgcookie );
  57 .sp
  58 .BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr );
  59 .sp
  60 .BI "void *mpool_get(MPOOL *" mp ", pgno_t " pgno ", unsigned int " flags );
  61 .sp
  62 .BI "int mpool_put(MPOOL *" mp ", void *" pgaddr ", unsigned int " flags );
  63 .sp
  64 .BI "int mpool_sync(MPOOL *" mp );
  65 .sp
  66 .BI "int mpool_close(MPOOL *" mp );
  67 .fi
  68 .SH 説明
  69 .\"O .I Mpool
  70 .\"O is the library interface intended to provide page oriented buffer management
  71 .\"O of files.
  72 .\"O The buffers may be shared between processes.
  73 .I mpool
  74 は、ファイルに対するページ指向のバッファ管理を実装した
  75 ライブラリインターフェイスである。
  76 .PP
  77 .\"O The function
  78 .\"O .BR mpool_open ()
  79 .\"O initializes a memory pool.
  80 関数
  81 .BR mpool_open ()
  82 はメモリプールを初期化する。
  83 .\"O The
  84 .\"O .I key
  85 .\"O argument is the byte string used to negotiate between multiple
  86 .\"O processes wishing to share buffers.
  87 .\"O If the file buffers are mapped in shared memory, all processes using
  88 .\"O the same key will share the buffers.
  89 .I key
  90 引数はバイト文字列であり、バッファを共有したい複数プロセス間
  91 でのネゴシエーションに使われる。
  92 ファイルバッファが共有メモリにマップされると、
  93 同じキーを使うプロセスは全てバッファを共有する。
  94 .\"O If
  95 .\"O .I key
  96 .\"O is NULL, the buffers are mapped into private memory.
  97 .I key
  98 が NULL だと、バッファはプライベートなメモリに割り付けられる。
  99 .\"O The
 100 .\"O .I fd
 101 .\"O argument is a file descriptor for the underlying file, which must be seekable.
 102 .I fd
 103 引数はもとになるファイルのファイルデスクリプタである。
 104 このファイルデスクリプタはシーク可能でなくてはならない。
 105 .\"O If
 106 .\"O .I key
 107 .\"O is non-NULL and matches a file already being mapped, the
 108 .\"O .I fd
 109 .\"O argument is ignored.
 110 .I key
 111 が NULL でなく、かつ既にマップされているファイルにマッチした場合、
 112 .I fd
 113 引数は無視される。
 114 .PP
 115 .\"O The
 116 .\"O .I pagesize
 117 .\"O argument is the size, in bytes, of the pages into which the file is broken up.
 118 .I pagesize
 119 引数はバイト単位でのページサイズであり、ファイルはこのサイズに分割される。
 120 .\"O The
 121 .\"O .I maxcache
 122 .\"O argument is the maximum number of pages from the underlying file to cache
 123 .\"O at any one time.
 124 .I maxcache
 125 引数は基ファイルをキャッシュするときに用いる最大ページ数である。
 126 .\"NAKANO "at any one time" は「どんな瞬間においても (最大)」ですが、
 127 .\"NAKANO 省略可能でしょう。
 128 .\"O This value is not relative to the number of processes which share a file's
 129 .\"O buffers, but will be the largest value specified by any of the processes
 130 .\"O sharing the file.
 131 この値はファイルバッファを共有しているプロセスの数には関係ないが、
 132 ファイルを共有するプロセスが指定したうちの最大値が実際に用いられる。
 133 .PP
 134 .\"O The
 135 .\"O .BR mpool_filter ()
 136 .\"O function is intended to make transparent input and output processing of the
 137 .\"O pages possible.
 138 関数
 139 .BR mpool_filter ()
 140 は透過的なページ入出力処理を可能にする。
 141 .\"O If the
 142 .\"O .I pgin
 143 .\"O function is specified, it is called each time a buffer is read into the memory
 144 .\"O pool from the backing file.
 145 関数
 146 .I pgin
 147 が指定されていると、
 148 ファイルからメモリプールに読み込まれる度にこの関数が呼び出される。
 149 .\"O If the
 150 .\"O .I pgout
 151 .\"O function is specified, it is called each time a buffer is written into the
 152 .\"O backing file.
 153 関数
 154 .I pgout
 155 が指定されていと、
 156 バッファからファイルに書き出される度にこの関数が呼び出される。
 157 .\"O Both functions are called with the
 158 .\"O .I pgcookie
 159 .\"O pointer, the page number and a pointer to the page to being read or written.
 160 どちらの関数も、
 161 .I pgcookie
 162 ポインタ、ページ数、読み書きされるページへのポインタを引数にとる。
 163 .PP
 164 .\"O The function
 165 .\"O .BR mpool_new ()
 166 .\"O takes an
 167 .\"O .I MPOOL
 168 .\"O pointer and an address as arguments.
 169 関数
 170 .BR mpool_new ()
 171 は
 172 .I MPOOL
 173 ポインタとアドレスを引数にとる。
 174 .\"O If a new page can be allocated, a pointer to the page is returned and
 175 .\"O the page number is stored into the
 176 .\"O .I pgnoaddr
 177 .\"O address.
 178 新しいページが割り当て可能な場合、ページへのポインタが返され、
 179 ページ数が
 180 .I pgnoaddr
 181 アドレスに納められる。
 182 .\"O Otherwise, NULL is returned and
 183 .\"O .I errno
 184 .\"O is set.
 185 割り当てが不可能な場合は NULL が返され、
 186 .I errno
 187 がセットされる。
 188 .PP
 189 .\"O The function
 190 .\"O .BR mpool_get ()
 191 .\"O takes a
 192 .\"O .I MPOOL
 193 .\"O pointer and a page number as arguments.
 194 .\"O If the page exists, a pointer to the page is returned.
 195 .\"O Otherwise, NULL is returned and
 196 .\"O .I errno
 197 .\"O is set.
 198 .\"O The
 199 .\"O .I flags
 200 .\"O argument is not currently used.
 201 関数
 202 .BR mpool_get ()
 203 は
 204 .I MPOOL
 205 ポインタとページ数を引数にとる。ページが存在していると、
 206 ページへのポインタが返される。
 207 存在していないと NULL が返され、
 208 .I errno
 209 がセットされる。
 210 .I flags
 211 引き数は現在使用されていない。
 212 .PP
 213 .\"O The function
 214 .\"O .BR mpool_put ()
 215 .\"O unpins the page referenced by
 216 .\"O .IR pgaddr .
 217 関数
 218 .BR mpool_put ()
 219 は
 220 .I pgaddr
 221 が参照するページを解放する。
 222 .\"O .I pgaddr
 223 .\"O must be an address previously returned by
 224 .\"O .BR mpool_get ()
 225 .\"O or
 226 .\"O .BR mpool_new ().
 227 .I pgaddr
 228 は以前に
 229 .BR mpool_get ()
 230 か
 231 .BR mpool_new ()
 232 が返したアドレスでなければならない。
 233 .\"O The flag value is specified by ORing
 234 .\"O any of the following values:
 235 flag の値は以下の値の論理和で指定する。
 236 .TP
 237 .B MPOOL_DIRTY
 238 .\"O The page has been modified and needs to be written to the backing file.
 239 ページは変更されており、ファイルに書き出す必要がある。
 240 .PP
 241 .\"O .BR mpool_put ()
 242 .\"O returns 0 on success and \-1 if an error occurs.
 243 .BR mpool_put ()
 244 は成功すると 0 を、エラーがあると \-1 を返す。
 245 .PP
 246 .\"O The function
 247 .\"O .BR mpool_sync ()
 248 .\"O writes all modified pages associated with the
 249 .\"O .I MPOOL
 250 .\"O pointer to the
 251 .\"O backing file.
 252 関数
 253 .BR mpool_sync ()
 254 は
 255 .I MPOOL
 256 ポインタの示すページのうち、
 257 変更されたものを全てファイルに書き出す。
 258 .\"O .BR mpool_sync ()
 259 .\"O returns 0 on success and \-1 if an error occurs.
 260 .BR mpool_sync ()
 261 は成功すると 0 を、エラーがあると \-1 を返す。
 262 .PP
 263 .\"O The
 264 .\"O .BR mpool_close ()
 265 .\"O function free's up any allocated memory associated with the memory pool
 266 .\"O cookie.
 267 関数
 268 .BR mpool_close ()
 269 はメモリプールクッキーの示す割り当て済みのメモリを解放する。
 270 .\"O Modified pages are
 271 .\"O .B not
 272 .\"O written to the backing file.
 273 変更されたページはファイルに\fB書き出されない\fP。
 274 .\"O .BR mpool_close ()
 275 .\"O returns 0 on success and \-1 if an error occurs.
 276 .I mpool_close ()
 277 は成功すると 0 を、エラーがあると \-1 を返す。
 278 .SH エラー
 279 .\"O The
 280 .\"O .BR mpool_open ()
 281 .\"O function may fail and set
 282 .\"O .I errno
 283 .\"O for any of the errors specified for the library routine
 284 .\"O .BR malloc (3).
 285 関数
 286 .BR mpool_open ()
 287 は失敗するとライブラリルーチン
 288 .BR malloc (3)
 289 で指定されているエラーに応じた
 290 .I errno
 291 をセットする。
 292 .PP
 293 .\"O The
 294 .\"O .BR mpool_get ()
 295 .\"O function may fail and set
 296 .\"O .I errno
 297 .\"O for the following:
 298 関数
 299 .BR mpool_get ()
 300 は失敗すると次のような
 301 .I errno
 302 をセットする。
 303 .TP 15
 304 .B EINVAL
 305 .\"O The requested record doesn't exist.
 306 要求のあったレコードは存在しない。
 307 .PP
 308 .\"O The
 309 .\"O .BR mpool_new ()
 310 .\"O and
 311 .\"O .BR mpool_get ()
 312 .\"O functions may fail and set
 313 .\"O .I errno
 314 .\"O for any of the errors specified for the library routines
 315 .\"O .BR read (2),
 316 .\"O .BR write (2),
 317 .\"O and
 318 .\"O .BR malloc (3).
 319 関数
 320 .BR mpool_new ()
 321 と
 322 .BR mpool_get ()
 323 は失敗するとライブラリルーチン
 324 .BR read (2),
 325 .BR write (2),
 326 .BR malloc (3)
 327 で指定されているエラーに応じた
 328 .I errno
 329 をセットする。
 330 .PP
 331 .\"O The
 332 .\"O .BR mpool_sync ()
 333 .\"O function may fail and set
 334 .\"O .I errno
 335 .\"O for any of the errors specified for the library routine
 336 .\"O .BR write (2).
 337 関数
 338 .BR mpool_sync ()
 339 は失敗するとライブラリルーチン
 340 .BR write (2)
 341 で指定されているエラーに応じた
 342 .I errno
 343 をセットする。
 344 .PP
 345 .\"O The
 346 .\"O .BR mpool_close ()
 347 .\"O function may fail and set
 348 .\"O .I errno
 349 .\"O for any of the errors specified for the library routine
 350 .\"O .BR free (3).
 351 関数
 352 .BR mpool_close ()
 353 は失敗するとライブラリルーチン
 354 .BR free (3)
 355 で指定されているエラーに応じた
 356 .I errno
 357 をセットする。
 358 .\"O .SH "CONFORMING TO"
 359 .SH 準拠
 360 .\"O Not in POSIX.1-2001.
 361 .\"O Present on the BSDs.
 362 POSIX.1-2001 にはない。
 363 BSD 系に存在する。
 364 .SH 関連項目
 365 .BR btree (3),
 366 .BR dbopen (3),
 367 .BR hash (3),
 368 .BR recno (3)