--- Read this first
This version 2 of the libnfs API. It is not compatible with the earlier API.
All rpc_async() functions have been changed to
rpc_task().
The _task() functions return a struct rpc_pdu * which can later be used
to cancel an inflight command.
nfs_[]read and nfs_[p]write functions have new signatures.
Pay attention to any compiler warnings when compiling against this new API.
The symbol LIBNFS_API_V2 can be used to identify that the library uses the new
API.
This version of the library supports zero-copy read and write for NFS v3/4
LIBNFS is a client library for accessing NFS shares over a network.
LIBNFS offers three different APIs, for different use :
1, RAW : A fully async low level RPC library for NFS protocols
This API is described in include/libnfs-raw.h
it offers a fully async interface to raw XDR encoded blobs.
This API provides very flexible and precise control of the RPC issued.
examples/nfsclient-raw.c provides examples on how to use the raw API
2, NFS ASYNC : A fully asynchronous library for high level vfs functions
This API is described by the *_async() functions in include/libnfs.h.
This API provides a fully async access to posix vfs like functions such as
stat(), read(), ...
examples/nfsclient-async.c provides examples on how to use this API
3, NFS SYNC : A synchronous library for high level vfs functions
This API is described by the *_sync() functions in include/libnfs.h.
This API provides access to posix vfs like functions such as
stat(), read(), ...
examples/nfsclient-sync.c provides examples on how to use this API
NFSv4:
NFSv3 is the default but NFSv4 can be selected either by using the URL argument
version=4 or programatically calling nfs_set_version(nfs, NFS_V4) before
connecting to the server/share.
NFSv4.2 is selected with version=4.2 or nfs_set_version(nfs, NFS_V4_2). It
adds sparse file support: nfs_fallocate() for reserving, punching and zeroing
ranges, lseek() with SEEK_HOLE and SEEK_DATA, and the READ_PLUS and
WRITE_SAME operations. NFSv4.2 support is built by default and can be left
out with --disable-nfs4-2 (autoconf) or -DENABLE_NFS4_2=OFF (cmake).
Applications compile against it behind LIBNFS_FEATURE_NFS4_2, which libnfs.h
defines wherever the dialect exists at all. As with the other
LIBNFS_FEATURE_ macros that says the API is there rather than that this
particular build has it, so a build that dropped the dialect still reports
that only at run time, by failing nfs_set_version(nfs, NFS_V4_2).
CONCURRENCY AND NFSv4.2:
This matters if you drive libnfs hard, and it is the one place where the
NFSv4.2 dialect behaves differently from NFSv3 and NFSv4.0.
From NFSv4 minor version 1 onwards every request travels in a session slot,
and a slot carries one request at a time because the server's reply cache is
keyed on the (slot, sequence id) pair. The session therefore has a fixed
ceiling, set by the server, on how many requests can be outstanding at the
server at once. libnfs asks for 64 slots and uses whatever the server grants.
This is a limit on requests in flight, not on requests you may submit. libnfs
claims a slot as a request goes out on the wire rather than when you hand it
over, so queueing tens of thousands of async calls behaves exactly as it does
on NFSv3 and NFSv4.0; they are simply released onto the connection as slots
free up, and nothing is rejected or blocked at submission time.
What it does mean is that NFSv4.2 cannot keep more than the granted number of
requests at the server simultaneously, where NFSv4.0 has no such bound. If
your throughput comes from very deep request pipelining rather than from
large transfers, measure both dialects before choosing; NFSv4.0 may well be
faster for that shape of workload.
NFSv3 and NFSv4.0 have no sessions and none of this applies to them.
SERVER SUPPORT:
Libnfs supports building RPC servers.
Examples/portmapper-server.c is a small "portmapper" example written using
libnfs.
URL-FORMAT:
Libnfs uses RFC2224 style URLs extended with some minor libnfs extensions.
The basic syntax of these URLs is :
nfs://[@]<server|ipv4|ipv6>[:]/path[?arg=val[&arg=val]*]
Special characters in 'path' are escaped using %-hex-hex syntax.
For example '?' must be escaped if it occurs in a path as '?' is also used to
separate the path from the optional list of url arguments.
Example:
nfs://127.0.0.1/my?path/?version=4
must be escaped as
nfs://127.0.0.1/my%3Fpath/?version=4
This is the beginning of the README. Read the rest at the original. Read the full README ↗
