1.\" $NetBSD: puffs_ops.3,v 1.42 2015/02/16 10:48:56 wiz Exp $ 2.\" 3.\" Copyright (c) 2007 Antti Kantee. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd October 31, 2014 27.Dt PUFFS_OPS 3 28.Os 29.Sh NAME 30.Nm puffs_ops 31.Nd puffs callback operations 32.Sh LIBRARY 33.Lb libpuffs 34.Sh SYNOPSIS 35.In puffs.h 36.Ft int 37.Fo puffs_fs_statvfs 38.Fa "struct puffs_usermount *pu" "struct statvfs *sbp" 39.Fc 40.Ft int 41.Fo puffs_fs_sync 42.Fa "struct puffs_usermount *pu" "int waitfor" "const struct puffs_cred *pcr" 43.Fc 44.Ft int 45.Fo puffs_fs_fhtonode 46.Fa "struct puffs_usermount *pu" "void *fid" "size_t fidsize" 47.Fa "struct puffs_newinfo *pni" 48.Fc 49.Ft int 50.Fo puffs_fs_nodetofh 51.Fa "struct puffs_usermount *pu" "puffs_cookie_t cookie" "void *fid" 52.Fa "size_t *fidsize" 53.Fc 54.Ft void 55.Fo puffs_fs_extattrctl 56.Fa "struct puffs_usermount *pu" "int cmd" "puffs_cookie_t cookie" "int flags" 57.Fa "int attrnamespace" "const char *attrname" 58.Fc 59.Ft int 60.Fo puffs_fs_unmount 61.Fa "struct puffs_usermount *pu" "int flags" 62.Fc 63.Ft int 64.Fo puffs_node_lookup 65.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 66.Fa "struct puffs_newinfo *pni" "const struct puffs_cn *pcn" 67.Fc 68.Ft int 69.Fo puffs_node_create 70.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 71.Fa "struct puffs_newinfo *pni" "const struct puffs_cn *pcn" 72.Fa "const struct vattr *vap" 73.Fc 74.Ft int 75.Fo puffs_node_mknod 76.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 77.Fa "struct puffs_newinfo *pni" "const struct puffs_cn *pcn" 78.Fa "const struct vattr *vap" 79.Fc 80.Ft int 81.Fo puffs_node_open 82.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int mode" 83.Fa "const struct puffs_cred *pcr" 84.Fc 85.Ft int 86.Fo puffs_node_open2 87.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int modep" 88.Fa "const struct puffs_cred *pcr" "int *oflags" 89.Fc 90.Ft int 91.Fo puffs_node_close 92.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int flags" 93.Fa "const struct puffs_cred *pcr" 94.Fc 95.Ft int 96.Fo puffs_node_access 97.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int mode" 98.Fa "const struct puffs_cred *pcr" 99.Fc 100.Ft int 101.Fo puffs_node_getattr 102.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "struct vattr *vap" 103.Fa "const struct puffs_cred *pcr" 104.Fc 105.Ft int 106.Fo puffs_node_setattr 107.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "const struct vattr *vap" 108.Fa "const struct puffs_cred *pcr" 109.Fc 110.Ft int 111.Fo puffs_node_getattr_ttl 112.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "struct vattr *vap" 113.Fa "const struct puffs_cred *pcr" "struct timespec *va_ttl" 114.Fc 115.Ft int 116.Fo puffs_node_setattr_ttl 117.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "const struct vattr *vap" 118.Fa "const struct puffs_cred *pcr" "struct timespec *va_ttl" "int xflag" 119.Fc 120.Ft int 121.Fo puffs_node_poll 122.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int *events" 123.Fc 124.Ft int 125.Fo puffs_node_mmap 126.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int flags" 127.Fa "const struct puffs_cred *pcr" 128.Fc 129.Ft int 130.Fo puffs_node_fsync 131.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 132.Fa "const struct puffs_cred *pcr" "int flags" "off_t offlo" "off_t offhi" 133.Fc 134.Ft int 135.Fo puffs_node_seek 136.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "off_t oldoff" 137.Fa "off_t newoff" "const struct puffs_cred *pcr" 138.Fc 139.Ft int 140.Fo puffs_node_remove 141.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t targ" 142.Fa "const struct puffs_cn *pcn" 143.Fc 144.Ft int 145.Fo puffs_node_link 146.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t targ" 147.Fa "const struct puffs_cn *pcn" 148.Fc 149.Ft int 150.Fo puffs_node_rename 151.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t src" 152.Fa "const struct puffs_cn *pcn_src" "puffs_cookie_t targ_dir" 153.Fa "puffs_cookie_t targ" "const struct puffs_cn *pcn_targ" 154.Fc 155.Ft int 156.Fo puffs_node_mkdir 157.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 158.Fa "struct puffs_newinfo *pni" "const struct puffs_cn *pcn" 159.Fa "const struct vattr *vap" 160.Fc 161.Ft int 162.Fo puffs_node_rmdir 163.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t targ" 164.Fa "const struct puffs_cn *pcn" 165.Fc 166.Ft int 167.Fo puffs_node_readdir 168.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "struct dirent *dent" 169.Fa "off_t *readoff" "size_t *reslen" "const struct puffs_cred *pcr" 170.Fa "int *eofflag" "off_t *cookies" "size_t *ncookies" 171.Fc 172.Ft int 173.Fo puffs_node_symlink 174.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 175.Fa "struct puffs_newinfo *pni" 176.Fa "const struct puffs_cn *pcn_src" "const struct vattr *vap" 177.Fa "const char *link_target" 178.Fc 179.Ft int 180.Fo puffs_node_readlink 181.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 182.Fa "const struct puffs_cred *pcr" "char *link" "size_t *linklen" 183.Fc 184.Ft int 185.Fo puffs_node_read 186.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "uint8_t *buf" 187.Fa "off_t offset" "size_t *resid" "const struct puffs_cred *pcr" "int ioflag" 188.Fc 189.Ft int 190.Fo puffs_node_write 191.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "uint8_t *buf" 192.Fa "off_t offset" "size_t *resid" "const struct puffs_cred *pcr" "int ioflag" 193.Fc 194.Ft int 195.Fo puffs_node_write2 196.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "uint8_t *buf" 197.Fa "off_t offset" "size_t *resid" "const struct puffs_cred *pcr" "int ioflag" 198.Fa "int xflag" 199.Fc 200.Ft int 201.Fo puffs_node_abortop 202.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 203.Fa "const struct puffs_cn *pcn" 204.Fc 205.Ft int 206.Fo puffs_node_getextattr 207.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace" 208.Fa "const char *attrname" "size_t *attrsize" "uint8_t *attr" "size_t *resid" 209.Fa "const struct puffs_cred *pcr" 210.Fc 211.Ft int 212.Fo puffs_node_setextattr 213.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace" 214.Fa "const char *attrname" "uint8_t *attr" "size_t *resid" 215.Fa "const struct puffs_cred *pcr" 216.Fc 217.Ft int 218.Fo puffs_node_listextattr 219.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace" 220.Fa "size_t *attrssize" "uint8_t *attrs" "iint flag" "size_t *resid" 221.Fa "const struct puffs_cred *pcr" 222.Fc 223.Ft int 224.Fo puffs_node_deleteextattr 225.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace" 226.Fa "const char *attrname" 227.Fa "const struct puffs_cred *pcr" 228.Fc 229.Ft int 230.Fo puffs_node_fallocate 231.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "off_t pos" "off_t len" 232.Fc 233.Ft int 234.Fo puffs_node_fdiscard 235.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "off_t pos" "off_t len" 236.Fc 237.Ft int 238.Fo puffs_node_print 239.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 240.Fc 241.Ft int 242.Fo puffs_node_reclaim 243.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 244.Fc 245.Ft int 246.Fo puffs_node_reclaim2 247.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int nlookup" 248.Fc 249.Ft int 250.Fo puffs_node_inactive 251.Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" 252.Fc 253.Ft void 254.Fn puffs_setback "struct puffs_cc *pcc" "int op" 255.Ft void 256.Fn puffs_newinfo_setcookie "struct puffs_newinfo *pni" "puffs_cookie_t cookie" 257.Ft void 258.Fn puffs_newinfo_setvtype "struct puffs_newinfo *pni" "enum vtype vtype" 259.Ft void 260.Fn puffs_newinfo_setsize "struct puffs_newinfo *pni" "voff_t size" 261.Ft void 262.Fn puffs_newinfo_setrdev "struct puffs_newinfo *pni" "dev_t rdev" 263.Ft void 264.Fn puffs_newinfo_setva "struct puffs_newinfo *pni" "struct vattr *vap" 265.Ft void 266.Fn puffs_newinfo_setvattl "struct puffs_newinfo *pni" "struct timespec *va_ttl" 267.Ft void 268.Fn puffs_newinfo_setcnttl "struct puffs_newinfo *pni" "struct timespec *cn_ttl" 269.Sh DESCRIPTION 270The operations 271.Nm puffs 272requires to function can be divided into two categories: file system 273callbacks and node callbacks. 274The former affect the entire file system while the latter are targeted 275at a file or a directory and a file. 276They are roughly equivalent to the vfs and vnode operations in the 277kernel. 278.Pp 279All callbacks can be prototyped with the file system name and operation 280name using the macro 281.Fn PUFFSOP_PROTOS fsname . 282.Ss File system callbacks (puffs_fs) 283.Bl -tag -width xxxx 284.It Fn puffs_fs_statvfs "pu" "sbp" 285The following fields of the argument 286.Fa sbp 287need to be filled: 288.Bd -literal 289 * unsigned long f_bsize; file system block size 290 * unsigned long f_frsize; fundamental file system block size 291 * fsblkcnt_t f_blocks; number of blocks in file system, 292 * (in units of f_frsize) 293 * 294 * fsblkcnt_t f_bfree; free blocks avail in file system 295 * fsblkcnt_t f_bavail; free blocks avail to non-root 296 * fsblkcnt_t f_bresvd; blocks reserved for root 297 298 * fsfilcnt_t f_files; total file nodes in file system 299 * fsfilcnt_t f_ffree; free file nodes in file system 300 * fsfilcnt_t f_favail; free file nodes avail to non-root 301 * fsfilcnt_t f_fresvd; file nodes reserved for root 302 303.Ed 304.It Fn puffs_fs_sync "pu" "waitfor" "pcr" 305All the dirty buffers that have been cached at the file server 306level including metadata should be committed to stable storage. 307The 308.Fa waitfor 309parameter affects the operation. 310Possible values are: 311.Bl -tag -width XMNT_NOWAITX 312.It Dv MNT_WAIT 313Wait for all I/O for complete until returning. 314.It Dv MNT_NOWAIT 315Initiate I/O, but do not wait for completion. 316.It Dv MNT_LAZY 317Synchorize data not synchoronized by the file system syncer, 318i.e., data not written when 319.Fn node_fsync 320is called with 321.Dv FSYNC_LAZY . 322.El 323.Pp 324The credentials for the initiator of the sync operation are present in 325.Fa pcr 326and will usually be either file system or kernel credentials, but might 327also be user credentials. 328However, most of the time it is advisable to sync regardless of the 329credentials of the caller. 330.It Fn puffs_fs_fhtonode "pu" "fid" "fidsize" "pni" 331Translates a file handle 332.Fa fid 333to a node. 334The parameter 335.Fa fidsize 336indicates how large the file handle is. 337In case the file system's handles are static length, this parameter can 338be ignored as the kernel guarantees all file handles passed to the file 339server are of correct length. 340For dynamic length handles the field should be examined and 341.Er EINVAL 342returned in case the file handle length is not correct. 343.Pp 344This function provides essentially the same information to the kernel as 345.Fn puffs_node_lookup . 346The information is necessary for creating a new vnode corresponding to 347the file handle. 348.It Fn puffs_fs_nodetofh "pu" "cookie" "fid" "fidsize" 349Create a file handle from the node described by 350.Fa cookie . 351The file handle should contain enough information to reliably identify 352the node even after reboots and the pathname/inode being replaced by 353another file. 354If this is not possible, it is up to the author of the file system to 355act responsibly and decide if the file system can support file handles 356at all. 357.Pp 358For file systems which want dynamic length file handles, this function 359must check if the file handle space indicated by 360.Fa fidsize 361is large enough to accommodate the file handle for the node. 362If not, it must fill in the correct size and return 363.Er E2BIG . 364In either case, the handle length should be supplied to the kernel in 365.Fa fidsize . 366File systems with static length handles can ignore the size parameter as 367the kernel always supplies the correct size buffer. 368.It Fn puffs_fs_unmount "pu" "flags" 369Unmount the file system. 370The kernel has assumedly flushed all cached data when this callback 371is executed. 372If the file system cannot currently be safely be unmounted, for whatever 373reason, the kernel will honor an error value and not forcibly unmount. 374However, if the flag 375.Dv MNT_FORCE 376is not honored by the file server, the kernel will forcibly unmount 377the file system. 378.El 379.Ss Node callbacks 380These operations operate in the level of individual files. 381The file cookie is always provided as the second argument 382.Fa opc . 383If the operation is for a file, it will be the cookie of the file. 384The case the operation involves a directory (such as 385.Dq create file in directory ) , 386the cookie will be for the directory. 387Some operations take additional cookies to describe the rest of 388the operands. 389The return value 0 signals success, else an appropriate errno value 390should be returned. 391Please note that neither this list nor the descriptions are complete. 392.Bl -tag -width xxxx 393.It Fn puffs_node_lookup "pu" "opc" "pni" "pcn" 394This function is used to locate nodes, or in other words translate 395pathname components to file system data structures. 396The implementation should match the name in 397.Fa pcn 398against the existing entries in the directory provided by the cookie 399.Fa opc . 400If found, the cookie for the located node should be set in 401.Fa pni 402using 403.Fn puffs_newinfo_setcookie . 404Additionally, the vnode type and size (latter applicable to regular files only) 405should be set using 406.Fn puffs_newinfo_setvtype 407and 408.Fn puffs_newinfo_setsize , 409respectively. 410If the located entry is a block device or character device file, 411the dev_t for the entry should be set using 412.Fn puffs_newinfo_setrdev . 413.Pp 414If 415.Fn puffs_init 416was called with 417.Dv PUFFS_KFLAG_CACHE_FS_TTL 418then 419.Fn puffs_newinfo_setva , 420.Fn puffs_newinfo_setvattl , 421and 422.Fn puffs_newinfo_setcnttl 423can be called to specify the new node attributes, cached attributes 424time to live, and cached name time to live. 425.Pp 426The type of operation is found from 427.Va pcn-\*[Gt]pcn_nameiop : 428.Bl -tag -width XNAMEI_LOOKUPX 429.It Dv NAMEI_LOOKUP 430Normal lookup operation. 431.It Dv NAMEI_CREATE 432Lookup to create a node. 433.It Dv NAMEI_DELETE 434Lookup for node deletion. 435.It Dv NAMEI_RENAME 436Lookup for the target of a rename operation (source will be looked 437up using 438.Dv NAMEI_DELETE ) . 439.El 440.Pp 441The final component from a pathname lookup usually requires special 442treatment. 443It can be identified by looking at the 444.Va pcn-\*[Gt]pcn_flags 445fields for the flag 446.Dv PUFFSLOOKUP_ISLASTCN . 447For example, in most cases the lookup operation will want to check if 448a delete, rename or create operation has enough credentials to perform 449the operation. 450.Pp 451The return value 0 signals a found node and a nonzero value signals 452an errno. 453As a special case, 454.Er ENOENT 455signals "success" for cases where the lookup operation is 456.Dv NAMEI_CREATE 457or 458.Dv NAMEI_RENAME . 459Failure in these cases can be signalled by returning another appropriate 460error code, for example 461.Er EACCESS . 462.Pp 463Usually a null-terminated string for the next pathname component is 464provided in 465.Ar pcn-\*[Gt]pcn_name . 466In case the file system is using the option 467.Dv PUFFS_KFLAG_LOOKUP_FULLPNBUF , 468the remainder of the complete pathname under lookup is found in 469the same location. 470.Ar pcn-\*[Gt]pcn_namelen 471always specifies the length of the next component. 472If operating with a full path, the file system is allowed to consume 473more than the next component's length in node lookup. 474This is done by setting 475.Ar pcn-\*[Gt]pcn_consume 476to indicate the amount of 477.Em extra 478characters in addition to 479.Ar pcn-\*[Gt]pcn_namelen 480processed. 481.It Fn puffs_node_create "pu" "opc" "pni" "pcn" "va" 482.It Fn puffs_node_mkdir "pu" "opc" "pni" "pcn" "va" 483.It Fn puffs_node_mknod "pu" "opc" "pni" "pcn" "va" 484A file node is created in the directory denoted by the cookie 485.Fa opc 486by any of the above callbacks. 487The name of the new file can be found from 488.Fa pcn 489and the attributes are specified by 490.Fa va 491and the cookie for the newly created node should be set in 492.Fa pni . 493The only difference between these three is that they create a regular 494file, directory and device special file, respectively. 495.Pp 496In case of mknod, the device identifier can be found in 497.Fa va-\*[Gt]va_rdev . 498.It Fn puffs_node_open "pu" "opc" "mode" "pcr" 499.It Fn puffs_node_open2 "pu" "opc" "mode" "pcr" "oflags" 500Open the node denoted by the cookie 501.Fa opc . 502The parameter 503.Fa mode 504specifies the flags that 505.Xr open 2 506was called with, e.g. 507.Dv O_APPEND 508and 509.Dv O_NONBLOCK . 510.Fn puffs_node_open2 511allows the file system to pass back information for the file in 512.Fa oflags . 513The only implemented flag for now is 514.Dv PUFFS_OPEN_IO_DIRECT 515that cause file read/write to bypass the page cache. 516.It Fn puffs_node_close "pu" "opc" "flags" "pcr" 517Close a node. 518The parameter 519.Fa flags 520parameter describes the flags that the file was opened with. 521.It Fn puffs_node_access "pu" "opc" "mode" "pcr" 522Check if the credentials of 523.Fa pcr 524have the right to perform the operation specified by 525.Fa mode 526onto the node 527.Fa opc . 528The argument 529.Fa mode 530can specify read, write or execute by 531.Dv PUFFS_VREAD , 532.Dv PUFFS_VWRITE , 533and 534.Dv PUFFS_VEXEC , 535respectively. 536.It Fn puffs_node_getattr "pu" "opc" "va" "pcr" 537The attributes of the node specified by 538.Fa opc 539must be copied to the space pointed by 540.Fa va . 541.It Fn puffs_node_getattr_ttl "pu" "opc" "va" "pcr" "va_ttl" 542Same as 543.Fn puffs_node_getattr 544with cached attribute time to live specified in 545.Fa va_ttl 546.It Fn puffs_node_setattr "pu" "opc" "va" "pcr" 547The attributes for the node specified by 548.Fa opc 549must be set to those contained in 550.Fa va . 551Only fields of 552.Fa va 553which contain a value different from 554.Dv PUFFS_VNOVAL 555(typecast to the field's type!) contain a valid value. 556.It Fn puffs_node_setattr_ttl "pu" "opc" "va" "pcr" "va_ttl" "xflag" 557Same as 558.Fn puffs_node_setattr 559with cached attribute time to live specified in 560.Fa va_ttl . 561.Dv PUFFS_SETATTR_FAF 562will be set in 563.Fa xflag 564for Fire-And-Forget operations. 565.It Fn puffs_node_poll "pu" "opc" "events" 566Poll for events on node 567.Ar opc . 568If 569.Xr poll 2 570events specified in 571.Ar events 572are available, the function should set the bitmask to match available 573events and return immediately. 574Otherwise, the function should block (yield) until some events in 575.Ar events 576become available and only then set the 577.Ar events 578bitmask and return. 579.Pp 580In case this function returns an error, 581.Dv POLLERR 582(or its 583.Xr select 2 584equivalent) will be delivered to the calling process. 585.Pp 586.Em NOTE! 587The system call interface for 588.Fn poll 589contains a timeout parameter. 590At this level, however, the timeout is not supplied. 591In case input does not arrive, the file system should periodically 592unblock and return 0 new events to avoid hanging forever. 593This will hopefully be better supported by libpuffs in the future. 594.It Fn puffs_node_mmap "pu" "opc" "flags" "pcr" 595Called when a regular file is being memory mapped by 596.Xr mmap 2 . 597.Fa flags 598is currently always 0. 599.It Fn puffs_node_fsync "pu" "opc" "pcr" "flags" "offlo" "offhi" 600Sychronize a node's contents onto stable storage. 601This is necessary only if the file server caches some information 602before committing it. 603The parameter 604.Fa flags 605specifies the minimum level of sychronization required (XXX: they are 606not yet available). 607The parameters 608.Fa offlo 609and 610.Fa offhi 611specify the data offsets requiring to be synced. 612A high offset of 0 means sync from 613.Fa offlo 614to the end of the file. 615.It Fn puffs_node_seek "pu" "opc" "oldoff" "newoff" "pcr" 616Test if the node 617.Ar opc 618is seekable to the location 619.Ar newoff . 620The argument 621.Ar oldoff 622specifies the offset we are starting the seek from. 623Most file systems dealing only with regular will choose to not 624implement this. 625However, it is useful for example in cases where files are 626unseekable streams. 627.It Fn puffs_node_remove "pu" "opc" "targ" "pcn" 628.It Fn puffs_node_rmdir "pu" "opc" "targ" "pcn" 629Remove the node 630.Fa targ 631from the directory indicated by 632.Fa opc . 633The directory entry name to be removed is provided by 634.Fa pcn . 635The rmdir operation removes only directories, while the remove 636operation removes all other types except directories. 637.Pp 638It is paramount to note that the file system may not remove the 639node data structures at this point, only the directory entry and prevent 640lookups from finding the node again. 641This is to retain the 642.Ux 643open file semantics. 644The data may be removed only when 645.Fn puffs_node_reclaim 646or 647.Fn puffs_node_reclaim2 648is called for the node, as this assures there are no further users. 649.It Fn puffs_node_link "pu" "opc" "targ" "pcn" 650Create a hard link for the node 651.Fa targ 652into the directory 653.Fa opc . 654The argument 655.Fa pcn 656provides the directory entry name for the new link. 657.It Fn puffs_node_rename "pu" "src_dir" "src" "pcn_src" "targ_dir" "targ" "pcn_targ" 658Rename the node 659.Fa src 660with the name specified by 661.Fa pcn_src 662from the directory 663.Fa src_dir . 664The target directory and target name are given by 665.Fa targ_dir 666and 667.Fa pcn_targ , 668respectively. 669.Em If 670the target node already exists, it is specified by 671.Fa targ 672and must be replaced atomically. 673Otherwise 674.Fa targ 675is gives as 676.Dv NULL . 677.Pp 678It is legal to replace a directory node by another directory node with 679the means of rename if the target directory is empty, otherwise 680.Er ENOTEMPTY 681should be returned. 682All other types can replace all other types. 683In case a rename between incompatible types is attempted, the errors 684.Er ENOTDIR 685or 686.Er EISDIR 687should be returned, depending on the target type. 688.It Fn puffs_node_readdir "pu" "opc" "dent" "readoff" "reslen" "pcr" "eofflag" "cookies" "ncookies" 689To read directory entries, 690.Fn puffs_node_readdir 691is called. 692It should store directories as 693.Va struct dirent 694in the space pointed to by 695.Fa dent . 696The amount of space available is given by 697.Fa reslen 698and before returning it should be set to the amount of space 699.Em remaining 700in the buffer. 701The argument 702.Fa offset 703is used to specify the offset to the directory. 704Its intepretation is up to the file system and it should be set to 705signal the continuation point when there is no more room for the next 706entry in 707.Fa dent . 708It is most performant to return the maximal amount of directory 709entries each call. 710It is easiest to generate directory entries by using 711.Fn puffs_nextdent , 712which also automatically advances the necessary pointers. 713.Pp 714In case end-of-directory is reached, 715.Fa eofflag 716should be set to one. 717Note that even a new call to readdir may start where 718.Fa readoff 719points to end-of-directory. 720.Pp 721If the file system supports file handles, the arguments 722.Fa cookies 723and 724.Fa ncookies 725must be filled out. 726.Fa cookies 727is a vector for offsets corresponding to read offsets. 728One cookie should be filled out for each directory entry. 729The value of the cookie should equal the offset of the 730.Em next 731directory entry, i.e., which offset should be passed to readdir for 732the first entry read to be the entry following the current one. 733.Fa ncookies 734is the number of slots for cookies in the cookie vector upon entry to 735the function and must be set to the amount of cookies stored in the 736vector (i.e., amount of directory entries read) upon exit. 737There is always enough space in the cookie vector for the maximal number 738of entries that will fit into the directory entry buffer. 739For filling out the vector, the helper function 740.Fn PUFFS_STORE_DCOOKIE cookies ncookies offset 741can be used. 742This properly checks against 743.Fa cookies 744being 745.Dv NULL . 746Note that 747.Fa ncookies 748must be initialized to zero before the first call to 749.Fn PUFFS_STORE_DCOOKIE . 750.It Fn puffs_node_symlink "pu" "opc" "pni" "pcn_src" "va" "link_target" 751Create a symbolic link into the directory 752.Fa opc 753with the name in 754.Fa pcn_src 755and the initial attributes in 756.Fa va . 757The argument 758.Ar link_target 759contains a null-terminated string for the link target. 760The created node cookie should be set in 761.Fa pni . 762.It Fn puffs_node_readlink "pu" "opc" "pcr" "link" "linklen" 763Read the target of a symbolic link 764.Fa opc . 765The result is placed in the buffer pointed to by 766.Fa link . 767This buffer's length is given in 768.Fa linklen 769and it must be updated to reflect the real link length. 770A terminating nul character should not be put into the buffer and 771.Em "must not" 772be included in the link length. 773.It Fn puffs_node_read "pu" "opc" "buf" "offset" "resid" "pcr" "ioflag" 774Read the contents of a file 775.Fa opc . 776It will gather the data from 777.Fa offset 778in the file and read the number 779.Fa resid 780octets. 781The buffer is guaranteed to have this much space. 782The amount of data requested by 783.Fa resid 784should be read, except in the case of eof-of-file or an error. 785The parameter 786.Fa resid 787should be set to indicate the amount of request NOT completed. 788In the normal case this should be 0. 789.It Fn puffs_node_write "pu" "opc" "buf" "offset" "resid" "pcr" "ioflag" 790.It Fn puffs_node_write2 "pu" "opc" "buf" "offset" "resid" "pcr" "ioflag" \ 791"xflag" 792.Fn puffs_node_write 793writes data to a file 794.Fa opc 795at 796.Fa offset 797and extend the file if necessary. 798The number of octets written is indicated by 799.Fa resid ; 800everything must be written or an error will be generated. 801The parameter must be set to indicate the amount of data NOT written. 802In case the ioflag 803.Dv PUFFS_IO_APPEND 804is specified, the data should be appended to the end of the file. 805.Fn puffs_node_write2 806serves the same purpose as 807.Fn puffs_node_write 808with an additional 809.Fa xflag 810in which 811.Dv PUFFS_WRITE_FAF 812is set for Fire-And-Forget operations. 813.It Fn puffs_node_fallocate "pu" "opc" "pos" "len" 814Allocate 815.Fa len 816bytes of backing store at offset 817.Fa pos 818for the node referenced by the cookie 819.Fa opc . 820.It Fn puffs_node_fdiscard "pu" "opc" "pos" "len" 821Free 822.Fa len 823bytes of backing store (creating a hole) at offset 824.Fa pos 825for the node referenced by the cookie 826.Fa opc . 827.It Fn puffs_node_print "pu" "opc" 828Print information about node. 829This is used only for kernel-initiated diagnostic purposes. 830.It Fn puffs_node_reclaim "pu" "opc" 831The kernel will no longer reference the cookie and resources associated 832with it may be freed. 833In case the file 834.Fa opc 835has a link count of zero, it may be safely removed now. 836.It Fn puffs_node_reclaim2 "pu" "opc" "nlookup" 837Same as 838.Fn puffs_node_reclaim 839with an addditional argument for the number of lookups that have been done 840on the node (Node creation is counted as a lookup). This can be used by the 841file system to avoid a race condition, where the kernel sends a reclaim 842while it does not have received the reply for a lookup. 843If the file system tracks lookup count, and compares to 844.Fa nlookup 845it can detect this situation and ignore the reclaim. 846.Pp 847If the file system maps cookies to 848.Vt struct puffs_node 849then the framework will do that work, and 850.Fn puffs_node_reclaim 851can be reliabily used without the race condition. 852.It Fn puffs_node_abortop "pu" "opc" "pcn" 853In case the operation following lookup (e.g., mkdir or remove) is not 854executed for some reason, abortop will be issued. 855This is useful only for servers which cache state between lookup 856and a directory operation and is generally left unimplemented. 857.It Fn puffs_node_inactive "pu" "opc" 858The node 859.Fa opc 860has lost its last reference in the kernel. 861However, the cookie must still remain valid until 862.Fn puffs_node_reclaim 863or 864.Fn puffs_node_reclaim2 865is called. 866.It Fn puffs_setback "pcc" "op" 867Issue a "setback" operation which will be handled when the request response 868is returned to the kernel. 869Currently this can be only called from mmap, open, remove and rmdir. 870The valid parameters for 871.Ar op 872are 873.Dv PUFFS_SETBACK_INACT_N1 874and 875.Dv PUFFS_SETBACK_INACT_N2 . 876These signal that a file system mounted with 877.Dv PUFFS_KFLAG_IAONDEMAND 878should call the file system inactive method for the specified node. 879The node number 1 always means the operation cookie 880.Ar opc , 881while the node number 2 can be used to specify the second node argument 882present in some methods, e.g., remove. 883.It Fn puffs_newinfo_setcookie pni cookie 884Set cookie for node provided by this method to 885.Ar cookie . 886.It Fn puffs_newinfo_setvtype pni vtype 887Set the type of the newly located node to 888.Ar vtype . 889This call is valid only for 890.Fn lookup 891and 892.Fn fhtonode . 893.It Fn puffs_newinfo_setsize pni size 894Set the size of the newly located node to 895.Ar size . 896If left unset, the value defaults to 0. 897This call is valid only for 898.Fn lookup 899and 900.Fn fhtovp . 901.It Fn puffs_newinfo_setrdev pni rdev 902Set the type of the newly located node to 903.Ar vtype . 904This call is valid only for 905.Fn lookup 906and 907.Fn fhtovp 908producing device type nodes. 909.It Fn puffs_newinfo_setva pni vap 910Set the attributes for newly created vnode. 911This call is valid for 912.Fn lookup , 913.Fn create , 914.Fn mkdir , 915.Fn mknod , 916and 917.Fn symlink , 918if 919.Fn puffs_init 920was called with 921.Dv PUFFS_KFLAG_CACHE_FS_TTL 922flag set. 923.It Fn puffs_newinfo_setvattl pni va_ttl 924Set cached attribute time to live for newly created vnode. 925This call is valid for 926.Fn lookup , 927.Fn create , 928.Fn mkdir , 929.Fn mknod , 930and 931.Fn symlink , 932if 933.Fn puffs_init 934was called with 935.Dv PUFFS_KFLAG_CACHE_FS_TTL 936flag set. 937.It Fn puffs_newinfo_setcnttl pni cn_ttl 938Set cached name time to live for newly created vnode. 939This call is valid for 940.Fn lookup , 941.Fn create , 942.Fn mkdir , 943.Fn mknod , 944and 945.Fn symlink , 946if 947.Fn puffs_init 948was called with 949.Dv PUFFS_KFLAG_CACHE_FS_TTL 950flag set. 951.El 952.Sh SEE ALSO 953.Xr puffs 3 , 954.Xr vfsops 9 , 955.Xr vnodeops 9 956