{"id":15515152,"url":"https://github.com/fgasper/p5-net-libnfs","last_synced_at":"2026-03-18T16:53:53.309Z","repository":{"id":42775712,"uuid":"505452291","full_name":"FGasper/p5-Net-LibNFS","owner":"FGasper","description":"CPAN’s Net::LibNFS","archived":false,"fork":false,"pushed_at":"2023-01-20T16:51:15.000Z","size":2778,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-02T20:51:09.954Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"XS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FGasper.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-06-20T13:26:33.000Z","updated_at":"2022-10-05T17:42:07.000Z","dependencies_parsed_at":"2023-01-27T23:16:25.778Z","dependency_job_id":null,"html_url":"https://github.com/FGasper/p5-Net-LibNFS","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-Net-LibNFS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-Net-LibNFS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-Net-LibNFS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FGasper%2Fp5-Net-LibNFS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FGasper","download_url":"https://codeload.github.com/FGasper/p5-Net-LibNFS/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246085655,"owners_count":20721213,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T10:01:24.375Z","updated_at":"2026-01-07T13:34:08.541Z","avatar_url":"https://github.com/FGasper.png","language":"XS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nNet::LibNFS - User-land NFS in Perl via [libnfs](https://github.com/sahlberg/libnfs)\n\n# SYNOPSIS\n\nCreate an NFS context and configure it:\n\n    my $nfs = Net::LibNFS-\u003enew()-\u003eset(\n        version =\u003e 4,\n        client_name =\u003e 'my-nfs-client-name',\n    );\n\nBlocking I/O:\n\n    # Connect to the NFS server:\n    #\n    $nfs-\u003emount('some.server.name', '/the-mount-path');\n\n    # Open a directory:\n    #\n    my $dh = $nfs-\u003eopendir('path/to/dir');\n\n    # Print the names of directory members.\n    #\n    while (my $dir_obj = $dh-\u003eread()) {   # NB: read() returns an object!\n        print \"Name: \", $dir_obj-\u003ename(), $/;\n    }\n\n    $nfs-\u003eumount();\n\nNon-blocking I/O, using [IO::Async](https://metacpan.org/pod/IO%3A%3AAsync):\n\n    my $loop = IO::Async::Loop-\u003enew();\n\n    my $nfsa = $nfs-\u003eio_async($loop);\n\n    $nfsa-\u003emount('some.server.name', '/the-mount-path')-\u003ethen( sub {\n         return $nfsa-\u003eopendir('path/to/dir');\n    } )-\u003ethen( sub ($dh) {\n        while (my $dir_obj = $dh-\u003eread()) {\n            print \"Name: \", $dir_obj-\u003ename(), $/;\n        }\n    } )-\u003ethen( sub {\n        $nfsa-\u003eumount();\n    } )-\u003efinally( sub { $loop-\u003estop() } );\n\n    $loop-\u003erun();\n\n([AnyEvent](https://metacpan.org/pod/AnyEvent) and [Mojolicious](https://metacpan.org/pod/Mojolicious) are also supported.)\n\n# DESCRIPTION\n\n[libnfs](https://github.com/sahlberg/libnfs) allows you to access NFS\nshares in user-space. Thus you can read \u0026 write files via NFS even if you\ncan’t (or just would rather not) [mount(8)](http://man.he.net/man8/mount) them locally.\n\n# LINKING\n\nIf a shared libnfs is available and is version 5.0.0 or later we’ll\nlink (dynamically) against that.\nOtherwise we try to compile our own libnfs and bundle it (statically).\n\nA shared libnfs is usually preferable because it can receive updates on its\nown; a static libnfs locks you into that version of the library until you\nrebuild Net::LibNFS.\n\nIf you have a usable shared libnfs but for some reason still want\nto bundle a custom-built static one, set `NET_LIBNFS_LINK_STATIC` to a\ntruthy value in the environment as you run this distribution’s\n`Makefile.PL`.\n\n# CHARACTER ENCODING\n\nAll strings for Net::LibNFS are byte strings. Take care to decode/encode\nappropriately, and be sure to test with non-ASCII text (like `thîß`).\n\nOf note:\n[NFSv4’s official specification](https://datatracker.ietf.org/doc/html/rfc7530)\nstipulates that filesystem paths should be valid UTF-8, which suggests that\nthis library might express paths as character strings rather than byte strings.\n(This assumedly facilitates better interoperability with Windows and other\nOSes whose filesystems are conceptually Unicode.)\nIn practice, however, some NFS servers appear not to care about UTF-8\nvalidity. In that light, and for consistency with general POSIX practice,\nwe stick to byte strings.\n\nNonetheless, for best results, ensure all filesystem paths are valid UTF-8.\n\n# STATIC FUNCTIONS\n\n## @exports = mount\\_getexports( $SERVERNAME \\[, $TIMEOUT\\] )\n\nReturns a list of hashrefs. Each hashref has `dir` (string) and\n`groups` (array of strings).\n\n## @addresses = find\\_local\\_servers()\n\nReturns a list of addresses (as strings).\n\n# METHODS: GENERAL\n\n## $obj = _CLASS_-\u003enew()\n\nInstantiates this class.\n\n## $obj = _OBJ_-\u003eset( @OPTS\\_KV )\n\nA setter for multiple settings; e.g., where libnfs exposes\n`nfs_set_version()`, here you pass `version` with the appropriate\nvalue.\n\nRecognized options are as follows. (Some may be unavailable if you\nuse an older, shared libnfs.)\n\n- `version`\n- `client_name` and `verifier` (NFSv4 only)\n- `tcp_syncnt`, `uid`, `gid`, `debug`, `auto_traverse_mounts`,\n`dircache`, `autoreconnect`, `timeout`, `nfsport`, `mountport`\n- `unix_authn` (arrayref) - Sets UID, GID, and auxiliary GIDs\nat once. Clobbers (and is clobbered by) `uid` and `gid`.\n- `pagecache`, `pagecache_ttl`, `readahead`\n- `readmax`, `writemax`\n- `readdir_buffer` - Sets the maximum buffer size for `READDIRPLUS`\n(which is used by _OBJ_-\u003eopendir). Can be a two-element arrayref to set\n`dircount` and `maxcount` independently or an unsigned integer to set both\nto the same value.\n\n## $old\\_umask = _OBJ_-\u003eumask( $NEW\\_UMASK )\n\nLike Perl’s built-in.\n\n## $cwd = _OBJ_-\u003egetcwd()\n\nReturns _OBJ_’s current directory.\n\n# METHODS: NON-BLOCKING I/O\n\nThis library implements non-blocking I/O by deriving a separate NFS\ncontext object from the “plain” (blocking-I/O) one.\n\nThe following methods all return a [Net::LibNFS::Async](https://metacpan.org/pod/Net%3A%3ALibNFS%3A%3AAsync) instance:\n\n## $ASYNC\\_OBJ = _OBJ_-\u003eio\\_async( $LOOP )\n\n$LOOP is an [IO::Async::Loop](https://metacpan.org/pod/IO%3A%3AAsync%3A%3ALoop) instance.\n\n## $ASYNC\\_OBJ = _OBJ_-\u003eanyevent()\n\nUnlike `io_async()`, this doesn’t require a loop object because\n[AnyEvent](https://metacpan.org/pod/AnyEvent)’s context is a singleton.\n\n## $ASYNC\\_OBJ = _OBJ_-\u003emojo( \\[$REACTOR\\] )\n\n$REACTOR (a [Mojo::Reactor](https://metacpan.org/pod/Mojo%3A%3AReactor) instance) is optional;\nthe default is Mojo’s default reactor.\n\n# METHODS: GETTERS\n\n- `queue_length()`\n- `get_readmax()`, `get_writemax()`\n- `get_version()` (i.e., the active NFS version)\n- `getcwd()`\n\n# CONSTANTS\n\n- `NFS4_F_SETLK`, `NFS4_F_SETLKW`, `F_RDLCK`, `F_WRLCK`, \u0026\n`F_UNLCK` - See [Net::LibNFS::Filehandle](https://metacpan.org/pod/Net%3A%3ALibNFS%3A%3AFilehandle)’s `fcntl()`.\n\n# METHODS: BLOCKING I/O\n\n## $obj = _OBJ_-\u003emount( $SERVERNAME, $EXPORTNAME )\n\nAttempts to contact $SERVERNAME and set _OBJ_ to access $EXPORTNAME.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003eumount()\n\nReleases the current NFS connection.\n\nReturns _OBJ_.\n\n## $stat\\_obj = _OBJ_-\u003estat( $PATH )\n\nLike Perl’s `stat()` but returns a [Net::LibNFS::Stat](https://metacpan.org/pod/Net%3A%3ALibNFS%3A%3AStat) instance.\n\n## $stat\\_obj = _OBJ_-\u003elstat( $PATH )\n\nLike `stat()` above but won’t follow symbolic links.\n\n## $nfs\\_fh = _OBJ_-\u003eopen( $PATH, $FLAGS \\[, $MODE\\] )\n\nOpens a file and returns a [Net::LibNFS::Filehandle](https://metacpan.org/pod/Net%3A%3ALibNFS%3A%3AFilehandle) instance to\ninteract with it.\n\n## $obj = _OBJ_-\u003emkdir( $PATH \\[, $MODE\\] )\n\nCreates a directory.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003ermdir( $PATH )\n\nDeletes a directory.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003echdir( $PATH )\n\nChanges _OBJ_’s directory.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003emknod( $PATH, $MODE, $DEV )\n\nLike [mknod(2)](http://man.he.net/man2/mknod).\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003eunlink( $PATH )\n\nDeletes a file.\n\nReturns _OBJ_.\n\n## $nfs\\_dh = _OBJ_-\u003eopendir( $PATH )\n\nOpens a directory and returns a [Net::LibNFS::Dirhandle](https://metacpan.org/pod/Net%3A%3ALibNFS%3A%3ADirhandle) instance to\nread from it.\n\n## $statvfs\\_obj = _OBJ_-\u003estatvfs( $PATH )\n\nLike [statvfs(2)](http://man.he.net/man2/statvfs). Returns a [Net::LibNFS::StatVFS](https://metacpan.org/pod/Net%3A%3ALibNFS%3A%3AStatVFS) instance.\n\n## $destination = _OBJ_-\u003ereadlink( $PATH )\n\nReads a symlink directly.\n\n## $obj = _OBJ_-\u003echmod( $PATH, $MODE )\n\nSets a path’s mode.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003elchmod( $PATH, $MODE )\n\nLike `chmod()` above but won’t follow symbolic links.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003echown( $PATH, $UID, $GID )\n\nSets a path’s ownership.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003eutime( $PATH, $ATIME, $MTIME )\n\nUpdates $PATH’s atime \u0026 mtime. A time can be specified as either:\n\n- A nonnegative number (not necessarily an integer).\n- A reference to a 2-member array of nonnegative integers:\nseconds and microseconds.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003elutime( $PATH, $ATIME, $MTIME )\n\nLike `utime()` above but can operate on symlinks.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003elchown( $PATH, $MODE )\n\nLike `chown()` above but won’t follow symbolic links.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003elink( $OLDPATH, $NEWPATH )\n\nCreates a hard link.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003esymlink( $OLDPATH, $NEWPATH )\n\nCreates a symbolic link.\n\nReturns _OBJ_.\n\n## $obj = _OBJ_-\u003erename( $OLDPATH, $NEWPATH )\n\nRenames a filesystem path.\n\nReturns _OBJ_.\n\n# UNIMPLEMENTED\n\nThe following libnfs features are unimplemented here:\n\n- Authentication: Would be nice!\n- URL parsing: Seems redundant with [URI](https://metacpan.org/pod/URI).\n- `creat()` \u0026 `create()`: These are redundant with `open()`.\n- `access()` \u0026 `access2()`: Merely knowing whether a given\nfile/directory is accessible isn’t as useful as it may seem because\nby the time you actually _use_ the resource the permissions/ownership\ncould have changed. To prevent that race condition it’s better just to\n`open()`/`opendir()` and handle errors accordingly.\n- `lockf()`: Apparently redundant with `fcntl()`-based locks save\nfor the lock-test functionality, which is generally a misstep for the same\nreason as `access()` above: by the time you use the resource—in this case,\nrequest a lock on the file—the system state may have changed.\n\n# SEE ALSO\n\n[RFC 7530](https://datatracker.ietf.org/doc/html/rfc7530) is, as of this\nwriting, NFSv4’s official definition.\n\n# LICENSE \u0026 COPYRIGHT\n\nCopyright 2022 Gasper Software Consulting. All rights reserved.\n\nNet::LibNFS is licensed under the same terms as Perl itself (cf.\n[perlartistic](https://metacpan.org/pod/perlartistic)); **HOWEVER**, since Net::LibNFS links to libnfs, use of\nNet::LibNFS _may_ imply acceptance of libnfs’s own copyright terms.\nSee `libnfs/COPYING` in this distribution for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgasper%2Fp5-net-libnfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgasper%2Fp5-net-libnfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgasper%2Fp5-net-libnfs/lists"}