Network Lock Manager Protocol, Version 4

Introduction

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

Transport Address

Port Number

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

 

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

File Handles