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.
100
101           Note that a "config" callback will only handle keys not recognized
102           as callback names; when picking key=value pairs that you want your
103           script fragment to understand, be aware that if a future nbdkit
104           release creates a callback by that name, your "config" script
105           fragment will no longer see that key.
106
107           All of these parameters are optional.
108
109       missing=SCRIPT
110           The parameter "missing" defines a script that will be called in
111           place of any other callback not explicitly provided.  If omitted,
112           this defaults to the script "exit 2".
113

ENVIRONMENT VARIABLES

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

FILES

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

VERSION

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

SEE ALSO

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

AUTHORS

135       Richard W.M. Jones
136
138       Copyright (C) 2019 Red Hat Inc.
139

LICENSE

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