Add ioctl docs, and newlines in other needed places.

[perl-fuse.git] / Fuse.pm

diff --git a/Fuse.pm b/Fuse.pm
index 9a68207..1e3573d 100755 (executable)
--- a/Fuse.pm
+++ b/Fuse.pm
@@ -277,6 +277,7 @@ for Fuse API v2.6, will return "2.6".
 =head3 getattr
 
 Arguments:  filename.
 =head3 getattr
 
 Arguments:  filename.

+

 Returns a list, very similar to the 'stat' function (see
 perlfunc).  On error, simply return a single numeric scalar
 value (e.g. "return -ENOENT();").
 Returns a list, very similar to the 'stat' function (see
 perlfunc).  On error, simply return a single numeric scalar
 value (e.g. "return -ENOENT();").


@@ -312,6 +313,7 @@ Here are the meaning of the fields:
 =head3 readlink
 
 Arguments:  link pathname.
 =head3 readlink
 
 Arguments:  link pathname.

+

 Returns a scalar: either a numeric constant, or a text string.
 
 This is called when dereferencing symbolic links, to learn the target.
 Returns a scalar: either a numeric constant, or a text string.
 
 This is called when dereferencing symbolic links, to learn the target.


@@ -321,6 +323,7 @@ example rv: return "/proc/self/fd/stdin";
 =head3 getdir
 
 Arguments:  Containing directory name.
 =head3 getdir
 
 Arguments:  Containing directory name.

+

 Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
 
 This is used to obtain directory listings.  It's opendir(), readdir(), filldir() and closedir() all in one call.
 Returns a list: 0 or more text strings (the filenames), followed by a numeric errno (usually 0).
 
 This is used to obtain directory listings.  It's opendir(), readdir(), filldir() and closedir() all in one call.


@@ -330,6 +333,7 @@ example rv: return ('.', 'a', 'b', 0);
 =head3 mknod
 
 Arguments:  Filename, numeric modes, numeric device
 =head3 mknod
 
 Arguments:  Filename, numeric modes, numeric device

+

 Returns an errno (0 upon success, as usual).
 
 This function is called for all non-directory, non-symlink nodes,
 Returns an errno (0 upon success, as usual).
 
 This function is called for all non-directory, non-symlink nodes,


@@ -338,6 +342,7 @@ not just devices.
 =head3 mkdir
 
 Arguments:  New directory pathname, numeric modes.
 =head3 mkdir
 
 Arguments:  New directory pathname, numeric modes.

+

 Returns an errno.
 
 Called to create a directory.
 Returns an errno.
 
 Called to create a directory.


@@ -345,6 +350,7 @@ Called to create a directory.
 =head3 unlink
 
 Arguments:  Filename.
 =head3 unlink
 
 Arguments:  Filename.

+

 Returns an errno.
 
 Called to remove a file, device, or symlink.
 Returns an errno.
 
 Called to remove a file, device, or symlink.


@@ -352,6 +358,7 @@ Called to remove a file, device, or symlink.
 =head3 rmdir
 
 Arguments:  Pathname.
 =head3 rmdir
 
 Arguments:  Pathname.

+

 Returns an errno.
 
 Called to remove a directory.
 Returns an errno.
 
 Called to remove a directory.


@@ -359,6 +366,7 @@ Called to remove a directory.
 =head3 symlink
 
 Arguments:  Existing filename, symlink name.
 =head3 symlink
 
 Arguments:  Existing filename, symlink name.

+

 Returns an errno.
 
 Called to create a symbolic link.
 Returns an errno.
 
 Called to create a symbolic link.


@@ -366,6 +374,7 @@ Called to create a symbolic link.
 =head3 rename
 
 Arguments:  old filename, new filename.
 =head3 rename
 
 Arguments:  old filename, new filename.

+

 Returns an errno.
 
 Called to rename a file, and/or move a file from one directory to another.
 Returns an errno.
 
 Called to rename a file, and/or move a file from one directory to another.


@@ -373,6 +382,7 @@ Called to rename a file, and/or move a file from one directory to another.
 =head3 link
 
 Arguments:  Existing filename, hardlink name.
 =head3 link
 
 Arguments:  Existing filename, hardlink name.

+

 Returns an errno.
 
 Called to create hard links.
 Returns an errno.
 
 Called to create hard links.


@@ -380,6 +390,7 @@ Called to create hard links.
 =head3 chmod
 
 Arguments:  Pathname, numeric modes.
 =head3 chmod
 
 Arguments:  Pathname, numeric modes.

+

 Returns an errno.
 
 Called to change permissions on a file/directory/device/symlink.
 Returns an errno.
 
 Called to change permissions on a file/directory/device/symlink.


@@ -387,6 +398,7 @@ Called to change permissions on a file/directory/device/symlink.
 =head3 chown
 
 Arguments:  Pathname, numeric uid, numeric gid.
 =head3 chown
 
 Arguments:  Pathname, numeric uid, numeric gid.

+

 Returns an errno.
 
 Called to change ownership of a file/directory/device/symlink.
 Returns an errno.
 
 Called to change ownership of a file/directory/device/symlink.


@@ -394,6 +406,7 @@ Called to change ownership of a file/directory/device/symlink.
 =head3 truncate
 
 Arguments:  Pathname, numeric offset.
 =head3 truncate
 
 Arguments:  Pathname, numeric offset.

+

 Returns an errno.
 
 Called to truncate a file, at the given offset.
 Returns an errno.
 
 Called to truncate a file, at the given offset.


@@ -401,6 +414,7 @@ Called to truncate a file, at the given offset.
 =head3 utime
 
 Arguments:  Pathname, numeric actime, numeric modtime.
 =head3 utime
 
 Arguments:  Pathname, numeric actime, numeric modtime.

+

 Returns an errno.
 
 Called to change access/modification times for a file/directory/device/symlink.
 Returns an errno.
 
 Called to change access/modification times for a file/directory/device/symlink.


@@ -409,6 +423,7 @@ Called to change access/modification times for a file/directory/device/symlink.
 
 Arguments:  Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
 and O_SYNC, constants you can import from POSIX), fileinfo hash reference.
 
 Arguments:  Pathname, numeric flags (which is an OR-ing of stuff like O_RDONLY
 and O_SYNC, constants you can import from POSIX), fileinfo hash reference.

+

 Returns an errno, a file handle (optional).
 
 No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().
 Returns an errno, a file handle (optional).
 
 No creation, or trunctation flags (O_CREAT, O_EXCL, O_TRUNC) will be passed to open().


@@ -422,6 +437,7 @@ Optionally a file handle may be returned, which will be passed to subsequent rea
 =head3 read
 
 Arguments:  Pathname, numeric requested size, numeric offset, file handle
 =head3 read
 
 Arguments:  Pathname, numeric requested size, numeric offset, file handle

+

 Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
 
 Called in an attempt to fetch a portion of the file.
 Returns a numeric errno, or a string scalar with up to $requestedsize bytes of data.
 
 Called in an attempt to fetch a portion of the file.


@@ -437,6 +453,7 @@ Called in an attempt to write (or overwrite) a portion of the file.  Be prepared
 =head3 statfs
 
 Arguments:  none
 =head3 statfs
 
 Arguments:  none

+

 Returns any of the following:
 
 -ENOANO()
 Returns any of the following:
 
 -ENOANO()


@@ -452,6 +469,7 @@ or
 =head3 flush
 
 Arguments: Pathname, file handle
 =head3 flush
 
 Arguments: Pathname, file handle

+

 Returns an errno or 0 on success.
 
 Called to synchronise any cached data. This is called before the file
 Returns an errno or 0 on success.
 
 Called to synchronise any cached data. This is called before the file


@@ -468,6 +486,7 @@ for every file with the same pathname and flags as were passed to open.
 =head3 fsync
 
 Arguments: Pathname, numeric flags
 =head3 fsync
 
 Arguments: Pathname, numeric flags

+

 Returns an errno or 0 on success.
 
 Called to synchronise the file's contents. If flags is non-zero,
 Returns an errno or 0 on success.
 
 Called to synchronise the file's contents. If flags is non-zero,


@@ -476,6 +495,7 @@ only synchronise the user data. Otherwise synchronise the user and meta data.
 =head3 setxattr
 
 Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE 
 =head3 setxattr
 
 Arguments: Pathname, extended attribute's name, extended attribute's value, numeric flags (which is an OR-ing of XATTR_CREATE and XATTR_REPLACE 

+

 Returns an errno or 0 on success.
 
 Called to set the value of the named extended attribute.
 Returns an errno or 0 on success.
 
 Called to set the value of the named extended attribute.


@@ -499,6 +519,7 @@ or:
 =head3 getxattr
 
 Arguments: Pathname, extended attribute's name
 =head3 getxattr
 
 Arguments: Pathname, extended attribute's name

+

 Returns an errno, 0 if there was no value, or the extended attribute's value.
 
 Called to get the value of the named extended attribute.
 Returns an errno, 0 if there was no value, or the extended attribute's value.
 
 Called to get the value of the named extended attribute.


@@ -506,11 +527,13 @@ Called to get the value of the named extended attribute.
 =head3 listxattr
 
 Arguments: Pathname
 =head3 listxattr
 
 Arguments: Pathname

+

 Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
 
 =head3 removexattr
 
 Arguments: Pathname, extended attribute's name
 Returns a list: 0 or more text strings (the extended attribute names), followed by a numeric errno (usually 0).
 
 =head3 removexattr
 
 Arguments: Pathname, extended attribute's name

+

 Returns an errno or 0 on success.
 
 =head3 opendir
 Returns an errno or 0 on success.
 
 =head3 opendir


@@ -525,6 +548,7 @@ that.
 =head3 readdir
 
 Arguments: Pathname of a directory, numeric offset, (optional) directory handle
 =head3 readdir
 
 Arguments: Pathname of a directory, numeric offset, (optional) directory handle

+

 Returns a list of 0 or more entries, followed by a numeric errno (usually 0).
 The entries can be simple strings (filenames), or arrays containing an
 offset number, the filename, and optionally an array ref containing the
 Returns a list of 0 or more entries, followed by a numeric errno (usually 0).
 The entries can be simple strings (filenames), or arrays containing an
 offset number, the filename, and optionally an array ref containing the


@@ -542,6 +566,7 @@ Note that if this call is implemented, it overrides getdir() ALWAYS.
 =head3 releasedir
 
 Arguments: Pathname of a directory, (optional) directory handle
 =head3 releasedir
 
 Arguments: Pathname of a directory, (optional) directory handle

+

 Returns an errno or 0 on success
 
 Called when there are no more references to an opened directory. Called once
 Returns an errno or 0 on success
 
 Called when there are no more references to an opened directory. Called once


@@ -552,6 +577,7 @@ code will not propagate to any corresponding closedir() calls.
 =head3 fsyncdir
 
 Arguments: Pathname of a directory, numeric flags, (optional) directory handle
 =head3 fsyncdir
 
 Arguments: Pathname of a directory, numeric flags, (optional) directory handle

+

 Returns an errno or 0 on success.
 
 Called to synchronize any changes to a directory's contents. If flag is
 Returns an errno or 0 on success.
 
 Called to synchronize any changes to a directory's contents. If flag is


@@ -561,16 +587,19 @@ metadata.
 =head3 init
 
 Arguments: None.
 =head3 init
 
 Arguments: None.

+

 Returns (optionally) an SV to be passed as private_data via fuse_get_context().
 
 =head3 destroy
 
 Arguments: (optional) private data SV returned from init(), if any.
 Returns (optionally) an SV to be passed as private_data via fuse_get_context().
 
 =head3 destroy
 
 Arguments: (optional) private data SV returned from init(), if any.

+

 Returns nothing.
 
 =head3 access
 
 Arguments: Pathname, access mode flags
 Returns nothing.
 
 =head3 access
 
 Arguments: Pathname, access mode flags

+

 Returns an errno or 0 on success.
 
 Determine if the user attempting to access the indicated file has access to
 Returns an errno or 0 on success.
 
 Determine if the user attempting to access the indicated file has access to


@@ -580,6 +609,7 @@ fuse_get_context(). See access(2) for more information.
 =head3 create
 
 Arguments: Pathname, create mask, open mode flags
 =head3 create
 
 Arguments: Pathname, create mask, open mode flags

+

 Returns errno or 0 on success, and (optional) file handle.
 
 Create a file with the path indicated, then open a handle for reading and/or
 Returns errno or 0 on success, and (optional) file handle.
 
 Create a file with the path indicated, then open a handle for reading and/or


@@ -589,6 +619,7 @@ open() as part of the call.
 =head3 ftruncate
 
 Arguments: Pathname, numeric offset, (optional) file handle
 =head3 ftruncate
 
 Arguments: Pathname, numeric offset, (optional) file handle

+

 Returns errno or 0 on success
 
 Like truncate(), but on an opened file.
 Returns errno or 0 on success
 
 Like truncate(), but on an opened file.


@@ -596,6 +627,7 @@ Like truncate(), but on an opened file.
 =head3 fgetattr
 
 Arguments: Pathname, (optional) file handle
 =head3 fgetattr
 
 Arguments: Pathname, (optional) file handle

+

 Returns a list, very similar to the 'stat' function (see
 perlfunc).  On error, simply return a single numeric scalar
 value (e.g. "return -ENOENT();").
 Returns a list, very similar to the 'stat' function (see
 perlfunc).  On error, simply return a single numeric scalar
 value (e.g. "return -ENOENT();").


@@ -605,6 +637,7 @@ Like getattr(), but on an opened file.
 =head3 lock
 
 Arguments: Pathname, numeric command code, hashref containing lock parameters, (optional) file handle
 =head3 lock
 
 Arguments: Pathname, numeric command code, hashref containing lock parameters, (optional) file handle

+

 Returns errno or 0 on success
 
 Used to lock or unlock regions of a file. Locking is handled locally, but this
 Returns errno or 0 on success
 
 Used to lock or unlock regions of a file. Locking is handled locally, but this


@@ -617,6 +650,7 @@ for the lock constants can be obtained by importing Fcntl.
 =head3 utimens
 
 Arguments: Pathname, last accessed time, last modified time
 =head3 utimens
 
 Arguments: Pathname, last accessed time, last modified time

+

 Returns errno or 0 on success
 
 Like utime(), but allows time resolution down to the nanosecond. Currently
 Returns errno or 0 on success
 
 Like utime(), but allows time resolution down to the nanosecond. Currently


@@ -629,6 +663,7 @@ Note that if this call is implemented, it overrides utime() ALWAYS.
 =head3 bmap
 
 Arguments: Pathname, numeric blocksize, numeric block number
 =head3 bmap
 
 Arguments: Pathname, numeric blocksize, numeric block number

+

 Returns errno or 0 on success, and physical block number if successful
 
 Used to map a block number offset in a file to the physical block offset
 Returns errno or 0 on success, and physical block number if successful
 
 Used to map a block number offset in a file to the physical block offset


@@ -636,6 +671,21 @@ on the block device backing the file system. This is intended for
 filesystems that are stored on an actual block device, with the 'blkdev'
 option passed.
 
 filesystems that are stored on an actual block device, with the 'blkdev'
 option passed.
 

+=head3 ioctl
+
+Arguments: Pathname, (signed) ioctl command code, flags, data if ioctl op is a write, (optional) file handle
+
+Returns errno or 0 on success, and data if ioctl op is a read
+
+Used to handle ioctl() operations on files. See ioctl(2) for more
+information on the fine details of ioctl operation numbers. May need to
+h2ph system headers to get the necessary macros; keep in mind the macros
+are highly OS-dependent.
+
+Keep in mind that read and write are from the client perspective, so
+read from our end means data is going *out*, and write means data is
+coming *in*. It can be slightly confusing.
+

 =head1 AUTHOR
 
 Mark Glines, E<lt>mark@glines.orgE<gt>
 =head1 AUTHOR
 
 Mark Glines, E<lt>mark@glines.orgE<gt>