man3/mpool.3

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   5 .\"
   6 .\"     @(#)mpool.3     8.1 (Berkeley) 6/4/93
   7 .\"
   8 .TH MPOOL 3 2021-03-22 "" "Linux Programmer's Manual"
   9 .UC 7
  10 .SH NAME
  11 mpool \- shared memory buffer pool
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <db.h>
  18 .B #include <mpool.h>
  19 .PP
  20 .BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \
  21 ", pgno_t " maxcache );
  22 .PP
  23 .BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *),"
  24 .BI "                  void (*" pgout ")(void *, pgno_t, void *),"
  25 .BI "                  void *" pgcookie );
  26 .PP
  27 .BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr );
  28 .BI "void *mpool_get(MPOOL *" mp ", pgno_t " pgno ", unsigned int " flags );
  29 .BI "int mpool_put(MPOOL *" mp ", void *" pgaddr ", unsigned int " flags );
  30 .PP
  31 .BI "int mpool_sync(MPOOL *" mp );
  32 .BI "int mpool_close(MPOOL *" mp );
  33 .fi
  34 .SH DESCRIPTION
  35 .IR "Note well" :
  36 This page documents interfaces provided in glibc up until version 2.1.
  37 Since version 2.2, glibc no longer provides these interfaces.
  38 Probably, you are looking for the APIs provided by the
  39 .I libdb
  40 library instead.
  41 .PP
  42 .I Mpool
  43 is the library interface intended to provide page oriented buffer management
  44 of files.
  45 The buffers may be shared between processes.
  46 .PP
  47 The function
  48 .BR mpool_open ()
  49 initializes a memory pool.
  50 The
  51 .I key
  52 argument is the byte string used to negotiate between multiple
  53 processes wishing to share buffers.
  54 If the file buffers are mapped in shared memory, all processes using
  55 the same key will share the buffers.
  56 If
  57 .I key
  58 is NULL, the buffers are mapped into private memory.
  59 The
  60 .I fd
  61 argument is a file descriptor for the underlying file, which must be seekable.
  62 If
  63 .I key
  64 is non-NULL and matches a file already being mapped, the
  65 .I fd
  66 argument is ignored.
  67 .PP
  68 The
  69 .I pagesize
  70 argument is the size, in bytes, of the pages into which the file is broken up.
  71 The
  72 .I maxcache
  73 argument is the maximum number of pages from the underlying file to cache
  74 at any one time.
  75 This value is not relative to the number of processes which share a file's
  76 buffers, but will be the largest value specified by any of the processes
  77 sharing the file.
  78 .PP
  79 The
  80 .BR mpool_filter ()
  81 function is intended to make transparent input and output processing of the
  82 pages possible.
  83 If the
  84 .I pgin
  85 function is specified, it is called each time a buffer is read into the memory
  86 pool from the backing file.
  87 If the
  88 .I pgout
  89 function is specified, it is called each time a buffer is written into the
  90 backing file.
  91 Both functions are called with the
  92 .I pgcookie
  93 pointer, the page number and a pointer to the page to being read or written.
  94 .PP
  95 The function
  96 .BR mpool_new ()
  97 takes an
  98 .I MPOOL
  99 pointer and an address as arguments.
 100 If a new page can be allocated, a pointer to the page is returned and
 101 the page number is stored into the
 102 .I pgnoaddr
 103 address.
 104 Otherwise, NULL is returned and
 105 .I errno
 106 is set.
 107 .PP
 108 The function
 109 .BR mpool_get ()
 110 takes an
 111 .I MPOOL
 112 pointer and a page number as arguments.
 113 If the page exists, a pointer to the page is returned.
 114 Otherwise, NULL is returned and
 115 .I errno
 116 is set.
 117 The
 118 .I flags
 119 argument is not currently used.
 120 .PP
 121 The function
 122 .BR mpool_put ()
 123 unpins the page referenced by
 124 .IR pgaddr .
 125 .I pgaddr
 126 must be an address previously returned by
 127 .BR mpool_get ()
 128 or
 129 .BR mpool_new ().
 130 The flag value is specified by ORing
 131 any of the following values:
 132 .TP
 133 .B MPOOL_DIRTY
 134 The page has been modified and needs to be written to the backing file.
 135 .PP
 136 .BR mpool_put ()
 137 returns 0 on success and \-1 if an error occurs.
 138 .PP
 139 The function
 140 .BR mpool_sync ()
 141 writes all modified pages associated with the
 142 .I MPOOL
 143 pointer to the
 144 backing file.
 145 .BR mpool_sync ()
 146 returns 0 on success and \-1 if an error occurs.
 147 .PP
 148 The
 149 .BR mpool_close ()
 150 function free's up any allocated memory associated with the memory pool
 151 cookie.
 152 Modified pages are
 153 .B not
 154 written to the backing file.
 155 .BR mpool_close ()
 156 returns 0 on success and \-1 if an error occurs.
 157 .SH ERRORS
 158 The
 159 .BR mpool_open ()
 160 function may fail and set
 161 .I errno
 162 for any of the errors specified for the library routine
 163 .BR malloc (3).
 164 .PP
 165 The
 166 .BR mpool_get ()
 167 function may fail and set
 168 .I errno
 169 for the following:
 170 .TP 15
 171 .B EINVAL
 172 The requested record doesn't exist.
 173 .PP
 174 The
 175 .BR mpool_new ()
 176 and
 177 .BR mpool_get ()
 178 functions may fail and set
 179 .I errno
 180 for any of the errors specified for the library routines
 181 .BR read (2),
 182 .BR write (2),
 183 and
 184 .BR malloc (3).
 185 .PP
 186 The
 187 .BR mpool_sync ()
 188 function may fail and set
 189 .I errno
 190 for any of the errors specified for the library routine
 191 .BR write (2).
 192 .PP
 193 The
 194 .BR mpool_close ()
 195 function may fail and set
 196 .I errno
 197 for any of the errors specified for the library routine
 198 .BR free (3).
 199 .SH CONFORMING TO
 200 Not in POSIX.1.
 201 Present on the BSDs.
 202 .SH SEE ALSO
 203 .BR btree (3),
 204 .BR dbopen (3),
 205 .BR hash (3),
 206 .BR recno (3)