| blob | 16858cab0b1e042152d80edc792f66c44e8f33a8 |
1 .\" Copyright (c) 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
3 .\"
4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. All advertising materials mentioning features or use of this software
14 .\" must display the following acknowledgement:
15 .\" This product includes software developed by the University of
16 .\" California, Berkeley and its contributors.
17 .\" 4. Neither the name of the University nor the names of its contributors
18 .\" may be used to endorse or promote products derived from this software
19 .\" without specific prior written permission.
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" SUCH DAMAGE.
32 .\" %%%LICENSE_END
33 .\"
34 .\" @(#)mpool.3 8.1 (Berkeley) 6/4/93
35 .\"
36 .TH MPOOL 3 2021-03-22 "" "Linux Programmer's Manual"
37 .UC 7
38 .SH NAME
39 mpool \- shared memory buffer pool
40 .SH SYNOPSIS
41 .nf
42 .B #include <db.h>
43 .B #include <mpool.h>
44 .PP
45 .BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \
46 ", pgno_t " maxcache );
47 .PP
48 .BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *),"
49 .BI " void (*" pgout ")(void *, pgno_t, void *),"
50 .BI " void *" pgcookie );
51 .PP
52 .BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr );
53 .BI "void *mpool_get(MPOOL *" mp ", pgno_t " pgno ", unsigned int " flags );
54 .BI "int mpool_put(MPOOL *" mp ", void *" pgaddr ", unsigned int " flags );
55 .PP
56 .BI "int mpool_sync(MPOOL *" mp );
57 .BI "int mpool_close(MPOOL *" mp );
58 .fi
59 .SH DESCRIPTION
60 .IR "Note well" :
61 This page documents interfaces provided in glibc up until version 2.1.
62 Since version 2.2, glibc no longer provides these interfaces.
63 Probably, you are looking for the APIs provided by the
64 .I libdb
65 library instead.
66 .PP
67 .I Mpool
68 is the library interface intended to provide page oriented buffer management
69 of files.
70 The buffers may be shared between processes.
71 .PP
72 The function
73 .BR mpool_open ()
74 initializes a memory pool.
75 The
76 .I key
77 argument is the byte string used to negotiate between multiple
78 processes wishing to share buffers.
79 If the file buffers are mapped in shared memory, all processes using
80 the same key will share the buffers.
81 If
82 .I key
83 is NULL, the buffers are mapped into private memory.
84 The
85 .I fd
86 argument is a file descriptor for the underlying file, which must be seekable.
87 If
88 .I key
89 is non-NULL and matches a file already being mapped, the
90 .I fd
91 argument is ignored.
92 .PP
93 The
94 .I pagesize
95 argument is the size, in bytes, of the pages into which the file is broken up.
96 The
97 .I maxcache
98 argument is the maximum number of pages from the underlying file to cache
99 at any one time.
100 This value is not relative to the number of processes which share a file's
101 buffers, but will be the largest value specified by any of the processes
102 sharing the file.
103 .PP
104 The
105 .BR mpool_filter ()
106 function is intended to make transparent input and output processing of the
107 pages possible.
108 If the
109 .I pgin
110 function is specified, it is called each time a buffer is read into the memory
111 pool from the backing file.
112 If the
113 .I pgout
114 function is specified, it is called each time a buffer is written into the
115 backing file.
116 Both functions are called with the
117 .I pgcookie
118 pointer, the page number and a pointer to the page to being read or written.
119 .PP
120 The function
121 .BR mpool_new ()
122 takes an
123 .I MPOOL
124 pointer and an address as arguments.
125 If a new page can be allocated, a pointer to the page is returned and
126 the page number is stored into the
127 .I pgnoaddr
128 address.
129 Otherwise, NULL is returned and
130 .I errno
131 is set.
132 .PP
133 The function
134 .BR mpool_get ()
135 takes an
136 .I MPOOL
137 pointer and a page number as arguments.
138 If the page exists, a pointer to the page is returned.
139 Otherwise, NULL is returned and
140 .I errno
141 is set.
142 The
143 .I flags
144 argument is not currently used.
145 .PP
146 The function
147 .BR mpool_put ()
148 unpins the page referenced by
149 .IR pgaddr .
150 .I pgaddr
151 must be an address previously returned by
152 .BR mpool_get ()
153 or
154 .BR mpool_new ().
155 The flag value is specified by ORing
156 any of the following values:
157 .TP
158 .B MPOOL_DIRTY
159 The page has been modified and needs to be written to the backing file.
160 .PP
161 .BR mpool_put ()
162 returns 0 on success and \-1 if an error occurs.
163 .PP
164 The function
165 .BR mpool_sync ()
166 writes all modified pages associated with the
167 .I MPOOL
168 pointer to the
169 backing file.
170 .BR mpool_sync ()
171 returns 0 on success and \-1 if an error occurs.
172 .PP
173 The
174 .BR mpool_close ()
175 function free's up any allocated memory associated with the memory pool
176 cookie.
177 Modified pages are
178 .B not
179 written to the backing file.
180 .BR mpool_close ()
181 returns 0 on success and \-1 if an error occurs.
182 .SH ERRORS
183 The
184 .BR mpool_open ()
185 function may fail and set
186 .I errno
187 for any of the errors specified for the library routine
188 .BR malloc (3).
189 .PP
190 The
191 .BR mpool_get ()
192 function may fail and set
193 .I errno
194 for the following:
195 .TP 15
196 .B EINVAL
197 The requested record doesn't exist.
198 .PP
199 The
200 .BR mpool_new ()
201 and
202 .BR mpool_get ()
203 functions may fail and set
204 .I errno
205 for any of the errors specified for the library routines
206 .BR read (2),
207 .BR write (2),
208 and
209 .BR malloc (3).
210 .PP
211 The
212 .BR mpool_sync ()
213 function may fail and set
214 .I errno
215 for any of the errors specified for the library routine
216 .BR write (2).
217 .PP
218 The
219 .BR mpool_close ()
220 function may fail and set
221 .I errno
222 for any of the errors specified for the library routine
223 .BR free (3).
224 .SH CONFORMING TO
225 Not in POSIX.1.
226 Present on the BSDs.
227 .SH SEE ALSO
228 .BR btree (3),
229 .BR dbopen (3),
230 .BR hash (3),
231 .BR recno (3)