4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
8 * * Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
11 * * Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
15 * * Neither the name of Red Hat nor the names of its contributors may be
16 * used to endorse or promote products derived from this software without
17 * specific prior written permission.
19 * THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
22 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
26 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
27 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 /* See nbdkit-filter(3) for documentation and how to write a filter. */
35 #ifndef NBDKIT_FILTER_H
36 #define NBDKIT_FILTER_H
40 #include <nbdkit-common.h>
46 #define NBDKIT_FILTER_API_VERSION 6 /* Corresponding to v1.16+ */
48 #define NBDKIT_ZERO_NONE 0
49 #define NBDKIT_ZERO_EMULATE 1
50 #define NBDKIT_ZERO_NATIVE 2
52 #ifdef NBDKIT_INTERNAL
53 /* Opaque types encapsulating all information needed for calling into
54 * the next filter or plugin.
56 typedef struct backend nbdkit_backend
;
57 typedef struct context nbdkit_context
;
58 typedef struct context nbdkit_next
;
60 typedef struct nbdkit_backend nbdkit_backend
;
61 typedef struct nbdkit_context nbdkit_context
;
62 typedef struct nbdkit_next_ops nbdkit_next
;
66 typedef int nbdkit_next_config (nbdkit_backend
*nxdata
,
67 const char *key
, const char *value
);
68 typedef int nbdkit_next_config_complete (nbdkit_backend
*nxdata
);
69 typedef int nbdkit_next_preconnect (nbdkit_backend
*nxdata
, int readonly
);
70 typedef int nbdkit_next_list_exports (nbdkit_backend
*nxdata
, int readonly
,
71 struct nbdkit_exports
*exports
);
72 typedef const char *nbdkit_next_default_export (nbdkit_backend
*nxdata
,
74 typedef int nbdkit_next_open (nbdkit_context
*context
,
75 int readonly
, const char *exportname
);
77 struct nbdkit_next_ops
{
78 /* These callbacks are only needed when managing the backend manually
79 * rather than via nbdkit_next_open.
81 int (*prepare
) (nbdkit_next
*nxdata
);
82 int (*finalize
) (nbdkit_next
*nxdata
);
84 /* These callbacks are the same as normal plugin operations. */
85 int64_t (*get_size
) (nbdkit_next
*nxdata
);
86 const char * (*export_description
) (nbdkit_next
*nxdata
);
87 int (*block_size
) (nbdkit_next
*nxdata
,
88 uint32_t *minimum
, uint32_t *preferred
, uint32_t *maximum
);
90 int (*can_write
) (nbdkit_next
*nxdata
);
91 int (*can_flush
) (nbdkit_next
*nxdata
);
92 int (*is_rotational
) (nbdkit_next
*nxdata
);
93 int (*can_trim
) (nbdkit_next
*nxdata
);
94 int (*can_zero
) (nbdkit_next
*nxdata
);
95 int (*can_fast_zero
) (nbdkit_next
*nxdata
);
96 int (*can_extents
) (nbdkit_next
*nxdata
);
97 int (*can_fua
) (nbdkit_next
*nxdata
);
98 int (*can_multi_conn
) (nbdkit_next
*nxdata
);
99 int (*can_cache
) (nbdkit_next
*nxdata
);
101 int (*pread
) (nbdkit_next
*nxdata
,
102 void *buf
, uint32_t count
, uint64_t offset
,
103 uint32_t flags
, int *err
);
104 int (*pwrite
) (nbdkit_next
*nxdata
,
105 const void *buf
, uint32_t count
, uint64_t offset
,
106 uint32_t flags
, int *err
);
107 int (*flush
) (nbdkit_next
*nxdata
, uint32_t flags
, int *err
);
108 int (*trim
) (nbdkit_next
*nxdata
, uint32_t count
, uint64_t offset
,
109 uint32_t flags
, int *err
);
110 int (*zero
) (nbdkit_next
*nxdata
, uint32_t count
, uint64_t offset
,
111 uint32_t flags
, int *err
);
112 int (*extents
) (nbdkit_next
*nxdata
, uint32_t count
, uint64_t offset
,
113 uint32_t flags
, struct nbdkit_extents
*extents
, int *err
);
114 int (*cache
) (nbdkit_next
*nxdata
, uint32_t count
, uint64_t offset
,
115 uint32_t flags
, int *err
);
117 /* Note: Actual instances of this struct contain additional opaque
118 * data not listed in this header; you cannot manually copy or
119 * initialize sizeof(struct nbdkit_next_ops) bytes, but must instead
120 * use unchanged pointers obtained from the nbdkit API.
124 /* Extent functions. */
125 struct nbdkit_extent
{
131 NBDKIT_EXTERN_DECL (struct nbdkit_extents
*, nbdkit_extents_new
,
132 (uint64_t start
, uint64_t end
));
133 NBDKIT_EXTERN_DECL (void, nbdkit_extents_free
, (struct nbdkit_extents
*));
134 NBDKIT_EXTERN_DECL (size_t, nbdkit_extents_count
,
135 (const struct nbdkit_extents
*));
136 NBDKIT_EXTERN_DECL (struct nbdkit_extent
, nbdkit_get_extent
,
137 (const struct nbdkit_extents
*, size_t));
138 NBDKIT_EXTERN_DECL (struct nbdkit_extents
*, nbdkit_extents_full
,
140 uint32_t count
, uint64_t offset
,
141 uint32_t flags
, int *err
));
142 NBDKIT_EXTERN_DECL (int, nbdkit_extents_aligned
,
144 uint32_t count
, uint64_t offset
,
145 uint32_t flags
, uint32_t align
,
146 struct nbdkit_extents
*extents
, int *err
));
148 /* Export functions. */
149 struct nbdkit_export
{
154 NBDKIT_EXTERN_DECL (struct nbdkit_exports
*, nbdkit_exports_new
,
156 NBDKIT_EXTERN_DECL (void, nbdkit_exports_free
, (struct nbdkit_exports
*));
157 NBDKIT_EXTERN_DECL (size_t, nbdkit_exports_count
,
158 (const struct nbdkit_exports
*));
159 NBDKIT_EXTERN_DECL (const struct nbdkit_export
, nbdkit_get_export
,
160 (const struct nbdkit_exports
*, size_t));
162 /* Manual management of backend access. */
163 NBDKIT_EXTERN_DECL (nbdkit_backend
*, nbdkit_context_get_backend
,
164 (nbdkit_context
*context
));
165 NBDKIT_EXTERN_DECL (nbdkit_next
*, nbdkit_next_context_open
,
166 (nbdkit_backend
*backend
, int readonly
,
167 const char *exportname
, int shared
));
168 NBDKIT_EXTERN_DECL (void, nbdkit_next_context_close
, (nbdkit_next
*next
));
169 NBDKIT_EXTERN_DECL (nbdkit_next
*, nbdkit_context_set_next
,
170 (nbdkit_context
*context
, nbdkit_next
*next
));
173 struct nbdkit_filter
{
174 /* Do not set these fields directly; use NBDKIT_REGISTER_FILTER.
175 * They exist so that we can diagnose filters compiled against one
176 * version of the header with a runtime compiled against a different
177 * version. As of API version 6, _version is also part of the
178 * guaranteed ABI, so we no longer have to remember to bump API
179 * versions regardless of other API/ABI changes later in the struct.
182 const char *_version
;
184 /* Because there is no ABI guarantee, new fields may be added where
185 * logically appropriate.
188 const char *longname
;
189 const char *description
;
192 void (*unload
) (void);
194 int (*config
) (nbdkit_next_config
*next
, nbdkit_backend
*nxdata
,
195 const char *key
, const char *value
);
196 int (*config_complete
) (nbdkit_next_config_complete
*next
,
197 nbdkit_backend
*nxdata
);
198 const char *config_help
;
199 int (*thread_model
) (void);
200 int (*get_ready
) (int thread_model
);
201 int (*after_fork
) (nbdkit_backend
*backend
);
202 void (*cleanup
) (nbdkit_backend
*backend
);
203 int (*preconnect
) (nbdkit_next_preconnect
*next
, nbdkit_backend
*nxdata
,
205 int (*list_exports
) (nbdkit_next_list_exports
*next
, nbdkit_backend
*nxdata
,
206 int readonly
, int is_tls
,
207 struct nbdkit_exports
*exports
);
208 const char * (*default_export
) (nbdkit_next_default_export
*next
,
209 nbdkit_backend
*nxdata
,
210 int readonly
, int is_tls
);
212 void * (*open
) (nbdkit_next_open
*next
, nbdkit_context
*context
,
213 int readonly
, const char *exportname
, int is_tls
);
214 void (*close
) (void *handle
);
216 int (*prepare
) (nbdkit_next
*next
,
217 void *handle
, int readonly
);
218 int (*finalize
) (nbdkit_next
*next
,
221 int64_t (*get_size
) (nbdkit_next
*next
,
223 const char * (*export_description
) (nbdkit_next
*next
, void *handle
);
224 int (*block_size
) (nbdkit_next
*next
, void *handle
,
225 uint32_t *minimum
, uint32_t *preferred
, uint32_t *maximum
);
227 int (*can_write
) (nbdkit_next
*next
,
229 int (*can_flush
) (nbdkit_next
*next
,
231 int (*is_rotational
) (nbdkit_next
*next
, void *handle
);
232 int (*can_trim
) (nbdkit_next
*next
,
234 int (*can_zero
) (nbdkit_next
*next
,
236 int (*can_fast_zero
) (nbdkit_next
*next
, void *handle
);
237 int (*can_extents
) (nbdkit_next
*next
,
239 int (*can_fua
) (nbdkit_next
*next
,
241 int (*can_multi_conn
) (nbdkit_next
*next
, void *handle
);
242 int (*can_cache
) (nbdkit_next
*next
,
245 int (*pread
) (nbdkit_next
*next
,
246 void *handle
, void *buf
, uint32_t count
, uint64_t offset
,
247 uint32_t flags
, int *err
);
248 int (*pwrite
) (nbdkit_next
*next
,
250 const void *buf
, uint32_t count
, uint64_t offset
,
251 uint32_t flags
, int *err
);
252 int (*flush
) (nbdkit_next
*next
,
253 void *handle
, uint32_t flags
, int *err
);
254 int (*trim
) (nbdkit_next
*next
,
255 void *handle
, uint32_t count
, uint64_t offset
, uint32_t flags
,
257 int (*zero
) (nbdkit_next
*next
,
258 void *handle
, uint32_t count
, uint64_t offset
, uint32_t flags
,
260 int (*extents
) (nbdkit_next
*next
,
261 void *handle
, uint32_t count
, uint64_t offset
, uint32_t flags
,
262 struct nbdkit_extents
*extents
, int *err
);
263 int (*cache
) (nbdkit_next
*next
,
264 void *handle
, uint32_t count
, uint64_t offset
, uint32_t flags
,
268 #define NBDKIT_REGISTER_FILTER(filter) \
271 struct nbdkit_filter * \
274 (filter)._api_version = NBDKIT_FILTER_API_VERSION; \
275 (filter)._version = NBDKIT_VERSION_STRING; \
283 #endif /* NBDKIT_FILTER_H */