NAME

nbdkit-golang-plugin - writing nbdkit plugins in Go

SYNOPSIS

 nbdkit /path/to/plugin.so [arguments...]

DESCRIPTION

This manual page describes how to write nbdkit plugins in compiled Golang code. Go plugins are compiled to *.so files (the same as plugins written in C) and are used in the same way.

WRITING A GOLANG NBDKIT PLUGIN

For examples of plugins written in Go, see: https://gitlab.com/nbdkit/nbdkit/blob/master/plugins/golang/examples

The minimal/minimal.go example is the smallest possible plugin, implementing only the required callbacks (Open, GetSize and PRead). Other examples show other nbdkit features.

Broadly speaking, Golang nbdkit plugins work like C ones, so you should read nbdkit-plugin(3) first.

To write a Golang nbdkit plugin, you must:

Can* callbacks

Important: If you implement PWrite it will not be called unless you also implement a CanWrite callback that returns true. (This is different from plugins written in C or other languages).

The same applies to Flush (CanFlush), Trim (CanTrim) and Zero (CanZero).

 func (c *MyConnection) CanWrite() (bool, error) {
         return true, nil
 }
 
 func (c *MyConnection) PWrite(buf []byte, offset uint64,
        flags uint32) error {
         // ...
}

Missing callbacks

The following callbacks are not yet implemented:

version
longname
description
magic_config_key
config_help
thread_model

At the moment the thread model is always NBDKIT_THREAD_MODEL_PARALLEL.

can_fast_zero
can_extents
can_fua
can_cache
extents
cache

VERSION

Golang plugins first appeared in nbdkit 1.20.

SEE ALSO

nbdkit(1), nbdkit-plugin(3).

AUTHORS

Richard W.M. Jones

COPYRIGHT

Copyright (C) 2020 Red Hat Inc.

LICENSE

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND 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 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.