]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1990, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
47009d5e | 4 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
5 | .\" |
6 | .\" @(#)mpool.3 8.1 (Berkeley) 6/4/93 | |
7 | .\" | |
45186a5d | 8 | .TH MPOOL 3 2021-03-22 "Linux man-pages (unreleased)" |
fea681da MK |
9 | .UC 7 |
10 | .SH NAME | |
11 | mpool \- shared memory buffer pool | |
364fbecf AC |
12 | .SH LIBRARY |
13 | Standard C library | |
8fc3b2cf | 14 | .RI ( libc ", " \-lc ) |
fea681da MK |
15 | .SH SYNOPSIS |
16 | .nf | |
495846d9 MK |
17 | .B #include <db.h> |
18 | .B #include <mpool.h> | |
68e4db0a | 19 | .PP |
62218dc0 | 20 | .BI "MPOOL *mpool_open(DBT *" key ", int " fd ", pgno_t " pagesize \ |
da8cb51e | 21 | ", pgno_t " maxcache ); |
68e4db0a | 22 | .PP |
62218dc0 | 23 | .BI "void mpool_filter(MPOOL *" mp ", void (*pgin)(void *, pgno_t, void *)," |
3dc4c74e | 24 | .BI " void (*" pgout ")(void *, pgno_t, void *)," |
da8cb51e | 25 | .BI " void *" pgcookie ); |
68e4db0a | 26 | .PP |
da8cb51e | 27 | .BI "void *mpool_new(MPOOL *" mp ", pgno_t *" pgnoaddr ); |
da8cb51e | 28 | .BI "void *mpool_get(MPOOL *" mp ", pgno_t " pgno ", unsigned int " flags ); |
da8cb51e | 29 | .BI "int mpool_put(MPOOL *" mp ", void *" pgaddr ", unsigned int " flags ); |
68e4db0a | 30 | .PP |
da8cb51e | 31 | .BI "int mpool_sync(MPOOL *" mp ); |
da8cb51e | 32 | .BI "int mpool_close(MPOOL *" mp ); |
fea681da MK |
33 | .fi |
34 | .SH DESCRIPTION | |
df21098d MK |
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. | |
847e0d88 | 41 | .PP |
0daa9e92 | 42 | .I Mpool |
fea681da MK |
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 | |
31e9a9ec | 48 | .BR mpool_open () |
fea681da MK |
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 | |
31e9a9ec | 80 | .BR mpool_filter () |
fea681da MK |
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. | |
fba59d25 | 91 | Both functions are called with the |
fea681da MK |
92 | .I pgcookie |
93 | pointer, the page number and a pointer to the page to being read or written. | |
94 | .PP | |
95 | The function | |
31e9a9ec | 96 | .BR mpool_new () |
4bd8c614 MK |
97 | takes an |
98 | .I MPOOL | |
99 | pointer and an address as arguments. | |
fea681da MK |
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. | |
09b235db MK |
104 | Otherwise, NULL is returned and |
105 | .I errno | |
106 | is set. | |
fea681da MK |
107 | .PP |
108 | The function | |
31e9a9ec | 109 | .BR mpool_get () |
4bd8c614 MK |
110 | takes an |
111 | .I MPOOL | |
112 | pointer and a page number as arguments. | |
fea681da | 113 | If the page exists, a pointer to the page is returned. |
09b235db MK |
114 | Otherwise, NULL is returned and |
115 | .I errno | |
116 | is set. | |
c4bb193f MK |
117 | The |
118 | .I flags | |
119 | argument is not currently used. | |
fea681da MK |
120 | .PP |
121 | The function | |
31e9a9ec | 122 | .BR mpool_put () |
fea681da MK |
123 | unpins the page referenced by |
124 | .IR pgaddr . | |
bee2a277 | 125 | .I pgaddr |
fea681da | 126 | must be an address previously returned by |
31e9a9ec | 127 | .BR mpool_get () |
fea681da | 128 | or |
31e9a9ec | 129 | .BR mpool_new (). |
cebca1bd | 130 | The flag value is specified by ORing |
fea681da MK |
131 | any of the following values: |
132 | .TP | |
4bd8c614 | 133 | .B MPOOL_DIRTY |
fea681da MK |
134 | The page has been modified and needs to be written to the backing file. |
135 | .PP | |
31e9a9ec | 136 | .BR mpool_put () |
fea681da MK |
137 | returns 0 on success and \-1 if an error occurs. |
138 | .PP | |
139 | The function | |
31e9a9ec | 140 | .BR mpool_sync () |
4bd8c614 MK |
141 | writes all modified pages associated with the |
142 | .I MPOOL | |
143 | pointer to the | |
fea681da | 144 | backing file. |
31e9a9ec | 145 | .BR mpool_sync () |
fea681da MK |
146 | returns 0 on success and \-1 if an error occurs. |
147 | .PP | |
148 | The | |
31e9a9ec | 149 | .BR mpool_close () |
fea681da MK |
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. | |
31e9a9ec | 155 | .BR mpool_close () |
fea681da MK |
156 | returns 0 on success and \-1 if an error occurs. |
157 | .SH ERRORS | |
158 | The | |
31e9a9ec | 159 | .BR mpool_open () |
fea681da MK |
160 | function may fail and set |
161 | .I errno | |
162 | for any of the errors specified for the library routine | |
31e9a9ec | 163 | .BR malloc (3). |
fea681da MK |
164 | .PP |
165 | The | |
31e9a9ec | 166 | .BR mpool_get () |
fea681da MK |
167 | function may fail and set |
168 | .I errno | |
169 | for the following: | |
170 | .TP 15 | |
747944fe | 171 | .B EINVAL |
fea681da MK |
172 | The requested record doesn't exist. |
173 | .PP | |
174 | The | |
31e9a9ec | 175 | .BR mpool_new () |
fea681da | 176 | and |
31e9a9ec | 177 | .BR mpool_get () |
fea681da MK |
178 | functions may fail and set |
179 | .I errno | |
180 | for any of the errors specified for the library routines | |
1368e847 MK |
181 | .BR read (2), |
182 | .BR write (2), | |
fea681da | 183 | and |
31e9a9ec | 184 | .BR malloc (3). |
fea681da MK |
185 | .PP |
186 | The | |
31e9a9ec | 187 | .BR mpool_sync () |
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 write (2). |
fea681da MK |
192 | .PP |
193 | The | |
31e9a9ec | 194 | .BR mpool_close () |
fea681da MK |
195 | function may fail and set |
196 | .I errno | |
197 | for any of the errors specified for the library routine | |
31e9a9ec | 198 | .BR free (3). |
3113c7f3 | 199 | .SH STANDARDS |
70928cce | 200 | Not in POSIX.1. |
a7fadb55 | 201 | Present on the BSDs. |
47297adb | 202 | .SH SEE ALSO |
31e9a9ec | 203 | .BR btree (3), |
f0c34053 | 204 | .BR dbopen (3), |
31e9a9ec MK |
205 | .BR hash (3), |
206 | .BR recno (3) |