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)