1nbdkit-eval-plugin(1)               NBDKIT               nbdkit-eval-plugin(1)
2
3
4

NAME

6       nbdkit-eval-plugin - write a shell script plugin on the command line
7

SYNOPSIS

9        nbdkit eval get_size='SCRIPT' pread='SCRIPT' pwrite='SCRIPT' [...]
10

DESCRIPTION

12       "nbdkit-eval-plugin" is an nbdkit(1) plugin which allows you to write
13       custom plugins as shell scripts snippets ‘eval’d on the command line.
14
15       A common alternative to this plugin is nbdkit-sh-plugin(1).  Both
16       plugins share the same source code and work in almost the same way.
17       You should read nbdkit-sh-plugin(1) first.  It is easier to describe
18       the differences between the two plugins and look at the examples below.
19
20       •   nbdkit-sh-plugin(1) plugins are written as a single script in a
21           separate file.  Eval plugins are shell script fragments written on
22           the nbdkit command line — there is no separate script file.
23
24       •   nbdkit-sh-plugin(1) has no way to know if a method is missing or
25           not and so each "can_*" method (eg. "can_write") must be written
26           explicitly.  In eval plugins you have the option of omitting
27           "can_*" methods if the associated callback (eg. "pwrite") is
28           defined.  In this way eval plugins work more like regular nbdkit
29           plugins.
30
31       •   Eval plugins can only use /bin/sh to run the script snippets, but
32           nbdkit-sh-plugin(1) (in spite of the name) can run any executable.
33
34       •   There is no "load" method (although there is an "unload" method and
35           all other methods are identical).
36

EXAMPLES

38       Create a 64M read-only disk of zeroes:
39
40        nbdkit eval get_size=' echo 64M ' \
41                       pread=' dd if=/dev/zero count=$3 iflag=count_bytes '
42
43       The following command is the eval plugin equivalent of
44       nbdkit-file-plugin(1) (except not as fast and missing many features):
45
46        nbdkit eval \
47          config='ln -sf "$(realpath "$3")" $tmpdir/file' \
48          get_size='stat -Lc %s $tmpdir/file' \
49          pread='dd if=$tmpdir/file skip=$4 count=$3 iflag=count_bytes,skip_bytes' \
50          pwrite='dd of=$tmpdir/file seek=$4 conv=notrunc oflag=seek_bytes' \
51          file=disk.img
52

PARAMETERS

54       after_fork=SCRIPT
55       block_size=SCRIPT
56       cache=SCRIPT
57       can_cache=SCRIPT
58       can_extents=SCRIPT
59       can_fast_zero=SCRIPT
60       can_flush=SCRIPT
61       can_fua=SCRIPT
62       can_multi_conn=SCRIPT
63       can_trim=SCRIPT
64       can_write=SCRIPT
65       can_zero=SCRIPT
66       close=SCRIPT
67       config=SCRIPT
68       config_complete=SCRIPT
69       default_export=SCRIPT
70       dump_plugin=SCRIPT
71       export_description=SCRIPT
72       extents=SCRIPT
73       flush=SCRIPT
74       get_ready=SCRIPT
75       get_size=SCRIPT
76       is_rotational=SCRIPT
77       list_exports=SCRIPT
78       default_export=SCRIPT
79       open=SCRIPT
80       pread=SCRIPT
81       preconnect=SCRIPT
82       pwrite=SCRIPT
83       thread_model=SCRIPT
84       trim=SCRIPT
85       unload=SCRIPT
86       zero=SCRIPT
87           Define the script associated with each method.  "SCRIPT" is a
88           fragment of shell script which is executed when nbdkit wants to
89           invoke the associated method.
90
91           If you are typing these commands at the shell, be careful about
92           quoting.  Normally you will need to enclose "SCRIPT" in '...'
93           (single quotes) to prevent it from being modified by your shell.
94
95           The script fragment behaves the same way as the corresponding
96           method in nbdkit-sh-plugin(1).  In particular, parameters are
97           identical, $tmpdir is present and used in the same way, the exit
98           code must be one of the valid exit codes described in that manual
99           page, and error handling works the same way too.  Likewise, nbdkit
100           --dump-plugin eval includes a line for max_known_status= in nbdkit
101           ≥ 1.34.
102
103           Note that a "config" callback will only handle keys not recognized
104           as callback names; when picking key=value pairs that you want your
105           script fragment to understand, be aware that if a future nbdkit
106           release creates a callback by that name, your "config" script
107           fragment will no longer see that key.
108
109           All of these parameters are optional.
110
111       missing=SCRIPT
112           The parameter "missing" defines a script that will be called in
113           place of any other callback not explicitly provided.  If omitted,
114           this defaults to the script "exit 2".
115

ENVIRONMENT VARIABLES

117       "tmpdir"
118           This is defined to the name of a temporary directory which can be
119           used by the script snippets.  It is deleted when nbdkit exits.
120

FILES

122       /bin/sh
123           Shell script fragments are executed using /bin/sh.
124
125       $plugindir/nbdkit-eval-plugin.so
126           The plugin.
127
128           Use "nbdkit --dump-config" to find the location of $plugindir.
129

VERSION

131       "nbdkit-eval-plugin" first appeared in nbdkit 1.18.
132

SEE ALSO

134       nbdkit(1), nbdkit-plugin(3), nbdkit-sh-plugin(1).  nbdkit-cc-plugin(1).
135

AUTHORS

137       Richard W.M. Jones
138
140       Copyright Red Hat
141

LICENSE

143       Redistribution and use in source and binary forms, with or without
144       modification, are permitted provided that the following conditions are
145       met:
146
147       •   Redistributions of source code must retain the above copyright
148           notice, this list of conditions and the following disclaimer.
149
150       •   Redistributions in binary form must reproduce the above copyright
151           notice, this list of conditions and the following disclaimer in the
152           documentation and/or other materials provided with the
153           distribution.
154
155       •   Neither the name of Red Hat nor the names of its contributors may
156           be used to endorse or promote products derived from this software
157           without specific prior written permission.
158
159       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
160       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
161       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
162       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
163       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
164       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
165       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
166       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
167       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
168       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
169       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
170
171
172
173nbdkit-1.36.2                     2023-11-26             nbdkit-eval-plugin(1)
Impressum