Previous section.

Protocols for Interworking: XNFS, Version 3W
Copyright © 1998 The Open Group

Network Lock Manager Protocol, Version 4

Introduction

This chapter specifies an additional protocol for the Network Lock Manager (NLM), the Version 4 protocol, which must be supported in addition to the Version 3 protocol specified in Chapter 10. The NLM Version 4 protocol is valid only when used with the Network File System Version 3 protocol; the NLM Version 3 protocol is valid only when used with the NFS Version 2 protocol.

This chapter only discusses the differences between the NLM Version 3 and Version 4 protocols. As with the NFS Version 3 protocol, almost all the names in the NLM Version 4 protocol have been changed to include a version number. This chapter does not discuss changes that consist solely of a name change.

RPC Information

Authentication
The NLM service uses AUTH_NONE in the NULL procedure. AUTH_UNIX, AUTH_DES or AUTH_KERB are used for all other procedures.
Transport Address
The NLM service is supported on both TCP/IP and UDP/IP. However, a client implementation may choose to only generate requests over the UDP/IP protocol.
Port Number
Consult the server's port mapper, described in Chapter 6, to find the port number on which the lock manager is registered.

Basic Data Types

uint64
typedef unsigned hyper uint64;
int64
typedef hyper int64;
uint32
typedef unsigned long uint32;
int32
typedef long int32;
nlm4_stats
enum nlm4_stats { NLM4_GRANTED = 0, NLM4_DENIED = 1, NLM4_DENIED_NOLOCKS = 2, NLM4_BLOCKED = 3, NLM4_DENIED_GRACE_PERIOD = 4, NLM4_DEADLCK = 5, NLM4_ROFS = 6, NLM4_STALE_FH = 7, NLM4_FBIG = 8, NLM4_FAILED = 9 };

The nlm4_stats value indicates the success or failure of a call. This version contains several new error codes, so that clients can provide more precise failure information to applications.

NLM4_GRANTED
The call completed successfully.

NLM4_DENIED
The call failed. For attempts to set a lock, this status implies that if the client retries the call later, it may succeed.

NLM4_DENIED_NOLOCKS

The call failed because the server could not allocate the necessary resources.

NLM4_BLOCKED
Indicates that a blocking request cannot be granted immediately. The server will issue an NLMPROC4_GRANTED callback to the client when the lock is granted.

NLM4_DENIED_GRACE_PERIOD

The call failed because the server is reestablishing old locks after a reboot and is not yet ready to resume normal service.

NLM4_DEADLCK
The request could not be granted and blocking would cause a deadlock.

NLM4_ROFS
The call failed because the remote file system is read-only. For example, some server implementations might not support exclusive locks on read-only file systems.

NLM4_STALE_FH
The call failed because it uses an invalid file handle. This can happen if the file has been removed or if access to the file has been revoked on the server.

NLM4_FBIG
The call failed because it specified a length or offset that exceeds the range supported by the server.

NLM4_FAILED
The call failed for some reason not already listed. The client should take this status as a strong hint not to retry the request.

nlm4_holder
struct nlm4_holder { bool exclusive; int32 svid; netobj oh; uint64 l_offset; uint64 l_len; };

Th nlm4_holder structure indicates the holder of a lock. The exclusive field tells whether the holder has an exclusive lock or a shared lock. The svid field identifies the process that is holding the lock. The oh field is an opaque object that identifies the host, or a process on the host, that is holding the lock. The l_len and l_offset fields identify the region that is locked. The only difference between the NLM Version 3 protocol and the NLM Version 4 protocol is that in the NLM Version 3 protocol, the l_len and l_offset fields are 32 bits wide, while they are 64 bits wide in the NLM Version 4 protocol.

nlm4_lock
struct nlm4_lock { string caller_name<LM_MAXSTRLEN>; netobj fh; netobj oh; int32 svid; uint64 l_offset; uint64 l_len; };

The nlm4_lock structure describes a lock request. The caller_name field identifies the host that is making the request. The fh field identifies the file to lock. The oh field is an opaque object that identifies the host, or a process on the host, that is making the request, and the svid field identifies the process that is making the request. The l_offset and l_len fields identify the region of the file that the lock controls. A l_len of zero means "to end-of-file."

There are two differences between the NLM Version 3 protocol and the NLM Version 4 protocol versions of this structure. First, in the NLM Version 3 protocol, the length and offset are 32 bits wide, while they are 64 bits wide in the NLM Version 4 protocol. Second, in the NLM Version 3 protocol, the file handle is a fixed-length NFS Version 2 protocol file handle, which is encoded as a byte count followed by a byte array. In the NFS Version 3 protocol, the file handle is already variable-length, so it is copied directly into the fh field. That is, the first four bytes of the fh field are the same as the byte count in an NFS Version 3 protocol nfs_fh3. The rest of the fh field contains the byte array from the NFS Version 3 protocol nfs_fh3.

nlm4_share
struct nlm4_share { string caller_name<LM_MAXSTRLEN>; netobj fh; netobj oh; fsh4_mode mode; fsh4_access access; };

The nlm4_share structure is used to support DOS file sharing. The caller_name field identifies the host making the request. The fh field identifies the file to be operated on. The oh field is an opaque object that identifies the host that is making the request. The mode and access fields specify the file-sharing and access modes. The encoding of fh is a byte count, followed by the file handle byte array. See the description of nlm4_lock for more details.

NLM Procedures

The procedures in the NLM Version 4 protocol are semantically the same as those in the NLM Version 3 protocol. The only semantic difference is the addition of a NULL procedure that can be used to test for server responsiveness. A syntactic change is that the procedures were renamed to avoid name conflicts with the values of nlm4_stats. Thus the procedure definition is as follows.
version NLM4_VERS { void NLMPROC4_NULL(void) = 0; nlm4_testres NLMPROC4_TEST(nlm4_testargs) = 1; nlm4_res NLMPROC4_LOCK(nlm4_lockargs) = 2; nlm4_res NLMPROC4_CANCEL(nlm4_cancargs) = 3; nlm4_res NLMPROC4_UNLOCK(nlm4_unlockargs) = 4; nlm4_res NLMPROC4_GRANTED(nlm4_testargs) = 5; void NLMPROC4_TEST_MSG(nlm4_testargs) = 6; void NLMPROC4_LOCK_MSG(nlm4_lockargs) = 7; void NLMPROC4_CANCEL_MSG(nlm4_cancargs) = 8; void NLMPROC4_UNLOCK_MSG(nlm4_unlockargs) = 9; void NLMPROC4_GRANTED_MSG(nlm4_testargs) = 10; void NLMPROC4_TEST_RES(nlm4_testres) = 11; void NLMPROC4_LOCK_RES(nlm4_res) = 12; void NLMPROC4_CANCEL_RES(nlm4_res) = 13; void NLMPROC4_UNLOCK_RES(nlm4_res) = 14; void NLMPROC4_GRANTED_RES(nlm4_res) = 15; nlm4_shareres NLMPROC4_SHARE(nlm4_shareargs) = 20; nlm4_shareres NLMPROC4_UNSHARE(nlm4_shareargs) = 21; nlm4_res NLMPROC4_NM_LOCK(nlm4_lockargs) = 22; void NLMPROC4_FREE_ALL(nlm4_notify) = 23; } = 4;

See the reference manual page for NLMPROC3_NULL for the definition of the additional NULL procedure.

Implementation Guidance

64-bit Offsets and Lengths
Some NFS Version 3 protocol servers can only support requests where the file offset or length fits in 32 or fewer bits. For these servers, the lock manager will have the same restriction. If such a lock manager receives a request that it cannot handle (because the offset or length uses more than 32 bits), it should return the NLM4_FBIG error.
File Handles
The change in the file handle format from the NFS Version 2 protocol to the NFS Version 3 protocol complicates the lock manager. First, the lock manager needs some way to tell when an NFS Version 2 protocol file handle refers to the same file as an NFS Version 3 protocol file handle. (This assumes that the lock manager supports both NLM Version 3 protocol clients and NLM Version 4 protocol clients.) Second, if the lock manager runs the file handle through a hashing function, the hashing function may need to be retuned to work with NFS Version 3 protocol file handles as well as NFS Version 2 protocol file handles.


Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index