Name

NFSPROC3_LOOKUP - Lookup Filename

Call Arguments

 

struct LOOKUP3args {
    diropargs3 what;
};

Return Arguments

 

struct LOOKUP3resok {
    nfs_fh3 object;
    post_op_attr obj_attributes;
    post_op_attr dir_attributes;
};

struct LOOKUP3resfail {
    post_op_attr dir_attributes;
};

union LOOKUP3res switch (nfsstat3 status) {
    case NFS3_OK:
        LOOKUP3resok resok;
    default:
        LOOKUP3resfail resfail;
};

RPC Procedure Description

 

LOOKUP3res
NFSPROC3_LOOKUP(LOOKUP3args) = 3;

Description

Procedure LOOKUP searches a directory for a specific name and returns the file handle for the corresponding file system object.

On entry, the arguments in LOOKUP3args are:

what

Object to look up.

dir

The file handle for the directory to search.

name

The filename to be searched for. See General File Name Requirements for more information on file names.

Upon successful return, LOOKUP3res.status is NFS3_OK and LOOKUP3res.resok contains:

object

The file handle of the object corresponding to what.name.

obj_attributes

The attributes of the object corresponding to what.name.

dir_attributes

The post-operation attributes of the directory what.dir.

Otherwise, LOOKUP3res.status contains the error on failure and LOOKUP3res.resfail contains the following:

dir_attributes

The post-operation attributes for the directory what.dir.

Implementation Guidance

At first glance, in the case where what.name refers to a mount point on the server, two different replies seem possible. The server can return either the file handle for the underlying directory that is mounted on it or the file handle of the root of the mounted directory. This ambiguity is simply resolved. A server will not allow a LOOKUP operation to cross a mount point to the root of a different file system, even if the file system is exported. This does not prevent a client from accessing a hierarchy of file systems exported by a server, but the client must mount each of the file systems individually so that the mount point crossing takes place on the client. A given server implementation may refine these rules given capabilities or limitations particular to that implementation.

Two filenames are distinguished, as in the NFS Version 2 protocol. The name "." is an alias for the current directory and the name ".." is an alias for the parent directory; that is, the directory that includes the specified directory as a member. There is no facility for dealing with a multiparented directory and NFS assumes a hierarchical organisation, organised as a single-rooted tree.

Unless the lookup is relative to the public filehandle, this procedure does not follow symbolic links. The client is responsible for all parsing of file names, including file names that are modified by symbolic links encountered during the lookup process.

WebNFS clients may use a pathname in place of the name where the lookup is relative to the public filehandle. In this case, the server must cross mount points when evaluating this pathname and follow any symbolic links that occur in all but the final component of the pathname.

Return Codes

NFS3ERR_IO

I/O error. Some sort of hard error occurred when the operation was in progress. This could be a disk error, for example.

NFS3ERR_NOENT

No such file or directory. The file or directory name specified does not exist.

NFS3ERR_ACCES

Permission denied. The caller does not have the correct permission to perform the requested operation. Contrast this with NFS3ERR_PERM, which restricts itself to owner permission failures.

NFS3ERR_NOTDIR

Not a directory. The caller specified a non-directory in a directory operation.

NFS3ERR_NAMETOOLONG

The filename in an operation was too long.

NFS3ERR_STALE

Invalid file handle. The file handle given in the arguments was invalid. The file referred to by that file handle no longer exists or access to it has been revoked.

NFS3ERR_BADHANDLE

Invalid NFS file handle. The file handle failed internal consistency checks.

NFS3ERR_SERVERFAULT

An error occurred on the server, which does not map to any of the valid NFS Version 3 protocol error values. The client should translate this into an appropriate error. Clients based on an XPG system may choose to translate this to EIO.