[ViewVC] Annotation of: cvs/Linux-NBD/README

NAME
    Linux::NBD::Client - client (device) side of a network block device

SYNOPSIS
     use Linux::NBD::Client;

DESCRIPTION
    WARNING: I talked to the author of the nbd driver because nbd is so
    extremely racy (right now, stopping it often causes oopses, a server
    crashing also often oopses etc..).

    It turned out that he doesn't care at all and nbd is basically
    unmaintained, so YMMV when using this module, especially when writing
    servers.

    He really should have said that on his nbd pages ;[.

    OTOH, it works relatively reliable when you don't stop the servers, so
    watch out and keep your fingers crossed.

METHODS
    $client = new Linux::NBD::Client [socket => $fh][, device =>
    "/dev/nbdX"], ...
        Create a new client.

        Unless "device" is given, an unused device node is looked up using
        the "device" method (this might result in an exception!).

    $client->socket ([$tcp_socket])
        Returns the current socket after setting a new one (if an argument
        is supplied). The socket *MUST* be a tcp socket. Believe me, bad
        things will happen if not.

        The special argument "undef" will try to clear the socket, if any
        was set.

    $client->device ([$new_device])
        Returns the current device node (e.g. "/dev/nbd2") after setting a
        new one if an argument is supplied.

        If the argument is "undef" it will search for an unallocated
        nbd-device and use it.

    $client->disconnect
        Tries to exit the server by sending a special disconnect message.

    $client->clear_queue
        Clears the request queue, if possible. Should be used before setting
        a new socket.

    $client->set_timeout ($timeout)
        Set the request timeout, in seconds.

    $client->set_blocksize ($blksize)
        Set the device block size in bytes, i.e. how big each block is (must
        be >512, <PAGESIZE and a power of two).

        Also rounds down the device size to be a multiple of the block size.

    $client->set_blocks ($nblocks)
        Set the device size in block units.

    $client->set_size ($bytes)
        Set the device size in octet units, will be rounded down to be a
        multiple of the block size.

    $client->run
        Closes all file descriptors except the server socket and enters the
        service loop (waits for read/write requests on the device and
        forwards them over the given socket). Only returns when somebody
        calls "disconnect" or the server is killed.

    $pid = $client->run_async
        Runs the service loop asynchronously and returns the pid of the
        newly created service process.

    $client->kill_async
        Kills any running async service. Please note that this also kills
        the socket, so you need to re-set the socket after this call.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

POD ERRORS
    Hey! The above document had some coding errors, which are explained
    below:

    Around line 258:
        =cut found outside a pod block. Skipping to next block.

Revision:	1.4
Committed:	Sun Nov 21 03:24:38 2010 UTC (13 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	rel-1_0, HEAD
Changes since 1.3:	+30 -18 lines
Log Message:	1.0
#	User	Rev	Content
1	root	1.2	NAME
2	root	1.3	Linux::NBD::Client - client (device) side of a network block device
3	root	1.2
4			SYNOPSIS
5			use Linux::NBD::Client;
6
7			DESCRIPTION
8			WARNING: I talked to the author of the nbd driver because nbd is so
9			extremely racy (right now, stopping it often causes oopses, a server
10			crashing also often oopses etc..).
11
12			It turned out that he doesn't care at all and nbd is basically
13			unmaintained, so YMMV when using this module, especially when writing
14			servers.
15
16			He really should have said that on his nbd pages ;[.
17
18			OTOH, it works relatively reliable when you don't stop the servers, so
19			watch out and keep your fingers crossed.
20
21			METHODS
22			$client = new Linux::NBD::Client [socket => $fh][, device =>
23	root	1.4	"/dev/nbdX"], ...
24	root	1.2	Create a new client.
25
26			Unless "device" is given, an unused device node is looked up using
27			the "device" method (this might result in an exception!).
28
29	root	1.4	$client->socket ([$tcp_socket])
30	root	1.2	Returns the current socket after setting a new one (if an argument
31	root	1.4	is supplied). The socket MUST be a tcp socket. Believe me, bad
32			things will happen if not.
33	root	1.2
34			The special argument "undef" will try to clear the socket, if any
35			was set.
36
37	root	1.4	$client->device ([$new_device])
38			Returns the current device node (e.g. "/dev/nbd2") after setting a
39	root	1.2	new one if an argument is supplied.
40
41			If the argument is "undef" it will search for an unallocated
42			nbd-device and use it.
43
44			$client->disconnect
45	root	1.4	Tries to exit the server by sending a special disconnect message.
46	root	1.2
47			$client->clear_queue
48			Clears the request queue, if possible. Should be used before setting
49			a new socket.
50
51	root	1.4	$client->set_timeout ($timeout)
52			Set the request timeout, in seconds.
53
54			$client->set_blocksize ($blksize)
55			Set the device block size in bytes, i.e. how big each block is (must
56			be >512, <PAGESIZE and a power of two).
57
58			Also rounds down the device size to be a multiple of the block size.
59	root	1.2
60	root	1.4	$client->set_blocks ($nblocks)
61			Set the device size in block units.
62	root	1.2
63	root	1.4	$client->set_size ($bytes)
64			Set the device size in octet units, will be rounded down to be a
65			multiple of the block size.
66	root	1.2
67			$client->run
68	root	1.4	Closes all file descriptors except the server socket and enters the
69			service loop (waits for read/write requests on the device and
70			forwards them over the given socket). Only returns when somebody
71	root	1.2	calls "disconnect" or the server is killed.
72
73			$pid = $client->run_async
74			Runs the service loop asynchronously and returns the pid of the
75			newly created service process.
76
77			$client->kill_async
78			Kills any running async service. Please note that this also kills
79			the socket, so you need to re-set the socket after this call.
80
81			AUTHOR
82			Marc Lehmann <schmorp@schmorp.de>
83			http://home.schmorp.de/
84
85	root	1.4	POD ERRORS
86			Hey! The above document had some coding errors, which are explained
87			below:
88
89			Around line 258:
90			=cut found outside a pod block. Skipping to next block.
91