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

ENVIRONMENT VARIABLES

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

FILES

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

VERSION

128       "nbdkit-eval-plugin" first appeared in nbdkit 1.18.
129

SEE ALSO

131       nbdkit(1), nbdkit-plugin(3), nbdkit-sh-plugin(1).  nbdkit-cc-plugin(1).
132

AUTHORS

134       Richard W.M. Jones
135
137       Copyright (C) 2019 Red Hat Inc.
138

LICENSE

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