.\" Automatically generated by Podwrapper::Man 1.10.3 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-blocksize-filter 1"
.TH nbdkit-blocksize-filter 1 "2019-01-26" "nbdkit-1.10.3" "NBDKIT"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdkit\-blocksize\-filter \- nbdkit blocksize filter
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& nbdkit \-\-filter=blocksize plugin [minblock=SIZE] [maxdata=SIZE] \e
\&     [maxlen=SIZE] [plugin\-args...]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-blocksize\-filter\*(C'\fR is a filter that ensures various block size
limits are met on transactions presented to the plugin.  The \s-1NBD\s0
protocol permits clients to send requests with a granularity as small
as 1 byte or as large as nearly 4 gigabytes, although it suggests that
portable clients should align requests to 512 bytes and not exceed 32
megabytes without prior coordination with the server.
.PP
Meanwhile, some plugins require requests to be aligned to 512\-byte
multiples, or may enforce a maximum transaction size to bound the time
or memory resources spent by any one command (note that nbdkit itself
refuses a read or write larger than 64 megabytes, while many other \s-1NBD\s0
servers limit things to 32 megabytes).  The blocksize filter can be
used to modify the client requests to meet the plugin restrictions.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
The nbdkit-blocksize-filter accepts the following parameters.
.IP "\fBminblock=\fR\s-1SIZE\s0" 4
.IX Item "minblock=SIZE"
The minimum block size and alignment to pass to the plugin.  This must
be a power of two, and no larger than 64k.  If omitted, this defaults
to 1 (that is, no minimum size restrictions).  The filter rounds up
read requests to alignment boundaries, performs read-modify-write
cycles for any unaligned head or tail of a write or zero request, and
silently ignores any unaligned head or tail of a trim request.  The
filter also truncates the plugin size down to an aligned value (as it
cannot safely operate on the unaligned tail); it is an error if this
would result in a size of 0.
.Sp
This parameter understands the suffix 'k' for 1024.
.IP "\fBmaxdata=\fR\s-1SIZE\s0" 4
.IX Item "maxdata=SIZE"
The maximum block size for any single transaction with data (read and
write).  If omitted, this defaults to 64 megabytes (that is, the
nbdkit maximum).  This need not be a power of two, but must be an
integer multiple of \f(CW\*(C`minblock\*(C'\fR.  The filter fragments any larger
client request into multiple plugin requests.
.Sp
This parameter understands the suffixes 'k', 'M', and 'G' for powers
of 1024.
.IP "\fBmaxlen=\fR\s-1SIZE\s0" 4
.IX Item "maxlen=SIZE"
The maximum length for any single transaction without data (trim and
zero).  If omitted, this defaults to 0xffffffff rounded down to
\&\f(CW\*(C`minsize\*(C'\fR alignment (that is, the inherent 32\-bit limit of the \s-1NBD\s0
protocol).  This need not be a power of two, but must be an integer
multiple of \f(CW\*(C`minblock\*(C'\fR, and should be at least as large as
\&\f(CW\*(C`maxdata\*(C'\fR.  The filter fragments any larger client request into
multiple plugin requests.
.Sp
This parameter understands the suffixes 'k', 'M', and 'G' for powers
of 1024.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Allow an arbitrary client to use the \s-1VDDK\s0 plugin (which is limited to
512\-byte blocks), without having to fix the client to avoid sending
unaligned requests:
.PP
.Vb 1
\& nbdkit \-\-filter=blocksize vddk minblock=512 file=/absolute/path/to/file.vmdk
.Ve
.PP
Allow an arbitrary client tuned to nbdkit's 64 megabyte sizing to
connect to a remote server that insists on 32 megabyte sizing, via the
nbd plugin:
.PP
.Vb 1
\& nbdkit \-\-filter=blocksize nbd maxdata=32M socket=/path/to/socket
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-nbd\-plugin\fR\|(1),
\&\fBnbdkit\-vddk\-plugin\fR\|(1),
\&\fBnbdkit\-filter\fR\|(3).
.SH "AUTHORS"
.IX Header "AUTHORS"
Eric Blake
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2018 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
.IP "\(bu" 4
Neither the name of Red Hat nor the names of its contributors may be
used to endorse or promote products derived from this software without
specific prior written permission.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0