Debian Codegraph @

upstream/debian-unstable/man3/mpool.3

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