2 * Copyright (C) 2013-2018 Red Hat Inc.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
16 * * Neither the name of Red Hat nor the names of its contributors may be
17 * used to endorse or promote products derived from this software without
18 * specific prior written permission.
20 * THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
21 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
23 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
27 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
28 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
30 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 /* See nbdkit-plugin(3) for documentation and how to write a plugin. */
36 #ifndef NBDKIT_PLUGIN_H
37 #define NBDKIT_PLUGIN_H
39 #include <nbdkit-common.h>
45 /* By default, a plugin gets API version 1; but you may request
46 * version 2 prior to including this header */
47 #ifndef NBDKIT_API_VERSION
48 #define NBDKIT_API_VERSION 1
49 #elif (NBDKIT_API_VERSION - 0) < 1 || NBDKIT_API_VERSION > 2
50 #error Unsupported API version
53 struct nbdkit_plugin
{
54 /* Do not set these fields directly; use NBDKIT_REGISTER_PLUGIN.
55 * They exist so that we can support plugins compiled against
56 * one version of the header with a runtime compiled against a
57 * different version with more (or fewer) fields.
59 uint64_t _struct_size
;
63 /* Plugins are responsible for these fields; see the documentation
64 * for semantics, and which fields are optional. New fields will
65 * only be added at the end of the struct.
70 const char *description
;
73 void (*unload
) (void);
75 int (*config
) (const char *key
, const char *value
);
76 int (*config_complete
) (void);
77 const char *config_help
;
79 void * (*open
) (int readonly
);
80 void (*close
) (void *handle
);
82 int64_t (*get_size
) (void *handle
);
84 int (*can_write
) (void *handle
);
85 int (*can_flush
) (void *handle
);
86 int (*is_rotational
) (void *handle
);
87 int (*can_trim
) (void *handle
);
89 #if NBDKIT_API_VERSION == 1
90 int (*pread
) (void *handle
, void *buf
, uint32_t count
, uint64_t offset
);
91 int (*pwrite
) (void *handle
, const void *buf
, uint32_t count
, uint64_t offset
);
92 int (*flush
) (void *handle
);
93 int (*trim
) (void *handle
, uint32_t count
, uint64_t offset
);
94 int (*zero
) (void *handle
, uint32_t count
, uint64_t offset
, int may_trim
);
96 int (*_pread_old
) (void *, void *, uint32_t, uint64_t);
97 int (*_pwrite_old
) (void *, const void *, uint32_t, uint64_t);
98 int (*_flush_old
) (void *);
99 int (*_trim_old
) (void *, uint32_t, uint64_t);
100 int (*_zero_old
) (void *, uint32_t, uint64_t, int);
103 int errno_is_preserved
;
105 void (*dump_plugin
) (void);
107 int (*can_fua
) (void *handle
);
108 #if NBDKIT_API_VERSION == 1
109 int (*_unused1
) (void *, void *, uint32_t, uint64_t);
110 int (*_unused2
) (void *, const void *, uint32_t, uint64_t, uint32_t);
111 int (*_unused3
) (void *, uint32_t);
112 int (*_unused4
) (void *, uint32_t, uint64_t, uint32_t);
113 int (*_unused5
) (void *, uint32_t, uint64_t, uint32_t);
115 int (*pread
) (void *handle
, void *buf
, uint32_t count
, uint64_t offset
,
117 int (*pwrite
) (void *handle
, const void *buf
, uint32_t count
,
118 uint64_t offset
, uint32_t flags
);
119 int (*flush
) (void *handle
, uint32_t flags
);
120 int (*trim
) (void *handle
, uint32_t count
, uint64_t offset
, uint32_t flags
);
121 int (*zero
) (void *handle
, uint32_t count
, uint64_t offset
, uint32_t flags
);
123 /* int (*set_exportname) (void *handle, const char *exportname); */
126 extern void nbdkit_set_error (int err
);
128 #define NBDKIT_REGISTER_PLUGIN(plugin) \
130 struct nbdkit_plugin * \
133 (plugin)._struct_size = sizeof (plugin); \
134 (plugin)._api_version = NBDKIT_API_VERSION; \
135 (plugin)._thread_model = THREAD_MODEL; \
143 #endif /* NBDKIT_PLUGIN_H */