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