The Perl Advent Calendar needs more articles for 2022. Submit your idea today!


Net::LibNFS::Filehandle - NFS filehandle (blocking I/O)



This class represents a libnfs filehandle and exposes a synchronous/blocking interface for interacting with that filehandle.

See Net::LibNFS for how to create instances.

See Net::LibNFS::Filehandle::Async for the async filehandle interface.


When Perl garbage-collects a filehandle, it closes the underlying file descriptor. This is a nice convenience that ideally we could do here, too. Whereas close() on a normal filehandle doesn’t block, though, the same operation on an NFS filehandle does block.

For that reason, this class DOES NOT CLEAN UP FILEHANDLES FOR YOU. If you neglect to close() an NFS filehandle, it’ll stay open until the NFS context itself (i.e., the Net::LibNFS instance) goes away.



Closes a filehandle. See "CLEANUP" for why it’s important to call this explicitly.

$buffer = OBJ->read( $MAXSIZE )

Tries to read up to $MAXSIZE bytes, and returns the buffer of bytes actually read.

$buffer = OBJ->pread( $OFFSET, $MAXSIZE )

Like read() above, but reads from a given $OFFSET and doesn’t alter the file pointer’s position.

$bytecount = OBJ->write( $BUFFER )

Tries to write $BUFFER.

Returns the number of bytes actually written.

$bytecount = OBJ->pwrite( $OFFSET, $BUFFER )

Analogous to pread() above. Tries to write $BUFFER at $OFFSET.

Returns the number of bytes actually written.

$cur_offset = OBJ->seek( $OFFSET, $WHENCE )

Seeks the filehandle to $OFFSET from $WHENCE (Fcntl’s SEEK_* constants).

$obj = OBJ->fcntl( $COMMAND, @ARGS )

Like fcntl(2). @ARGS depends on $COMMAND. Returns OBJ.

Currently recognized $COMMAND values are constants from Net::LibNFS:

  • NFS4_F_SETLK and NFS4_F_SETLKW - @ARGS are:

    • a type (Net::LibNFS’s *LCK constants)

    • “whence” (same as for seek() above)

    • OPTIONAL: the lock’s byte offset from “whence” (default is 0)

    • OPTIONAL: the lock’s length (default is 0, which means “until the file’s end”)

$stat = OBJ->stat()

Like fstat(2). Returns a Net::LibNFS::Stat instance.

$obj = OBJ->sync()

Like fsync(2). Returns OBJ.

$obj = OBJ->truncate( $LENGTH )

Like ftruncate(2). Returns OBJ.

$obj = OBJ->chmod( $MODE )

Like fchmod(2). Returns OBJ.

$obj = OBJ->chown( $UID, $GID )

Like fchown(2). Returns OBJ.