lib/libpuffs/puffs_ops.3

   1 .\"     $NetBSD: puffs_ops.3,v 1.29 2011/07/04 08:07:30 manu 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 February 5, 2012
  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_close
  87 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int flags"
  88 .Fa "const struct puffs_cred *pcr"
  89 .Fc
  90 .Ft int
  91 .Fo puffs_node_access
  92 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int mode"
  93 .Fa "const struct puffs_cred *pcr"
  94 .Fc
  95 .Ft int
  96 .Fo puffs_node_getattr
  97 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "struct vattr *vap"
  98 .Fa "const struct puffs_cred *pcr"
  99 .Fc
 100 .Ft int
 101 .Fo puffs_node_setattr
 102 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "const struct vattr *vap"
 103 .Fa "const struct puffs_cred *pcr"
 104 .Fc
 105 .Ft int
 106 .Fo puffs_node_poll
 107 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int *events"
 108 .Fc
 109 .Ft int
 110 .Fo puffs_node_mmap
 111 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int flags"
 112 .Fa "const struct puffs_cred *pcr"
 113 .Fc
 114 .Ft int
 115 .Fo puffs_node_fsync
 116 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc"
 117 .Fa "int flags"
 118 .Fc
 119 .Ft int
 120 .Fo puffs_node_seek
 121 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "off_t oldoff"
 122 .Fa "off_t newoff" "const struct puffs_cred *pcr"
 123 .Fc
 124 .Ft int
 125 .Fo puffs_node_remove
 126 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t targ"
 127 .Fa "const struct puffs_cn *pcn"
 128 .Fc
 129 .Ft int
 130 .Fo puffs_node_link
 131 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t targ"
 132 .Fa "const struct puffs_cn *pcn"
 133 .Fc
 134 .Ft int
 135 .Fo puffs_node_rename
 136 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t src"
 137 .Fa "const struct puffs_cn *pcn_src" "puffs_cookie_t targ_dir"
 138 .Fa "puffs_cookie_t targ" "const struct puffs_cn *pcn_targ"
 139 .Fc
 140 .Ft int
 141 .Fo puffs_node_mkdir
 142 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc"
 143 .Fa "struct puffs_newinfo *pni" "const struct puffs_cn *pcn"
 144 .Fa "const struct vattr *vap"
 145 .Fc
 146 .Ft int
 147 .Fo puffs_node_rmdir
 148 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "puffs_cookie_t targ"
 149 .Fa "const struct puffs_cn *pcn"
 150 .Fc
 151 .Ft int
 152 .Fo puffs_node_readdir
 153 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "struct dirent *dent"
 154 .Fa "off_t *readoff" "size_t *reslen" "const struct puffs_cred *pcr"
 155 .Fa "int *eofflag" "off_t *cookies" "size_t *ncookies"
 156 .Fc
 157 .Ft int
 158 .Fo puffs_node_symlink
 159 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc"
 160 .Fa "struct puffs_newinfo *pni"
 161 .Fa "const struct puffs_cn *pcn_src" "const struct vattr *vap"
 162 .Fa "const char *link_target"
 163 .Fc
 164 .Ft int
 165 .Fo puffs_node_readlink
 166 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc"
 167 .Fa "const struct puffs_cred *pcr" "char *link" "size_t *linklen"
 168 .Fc
 169 .Ft int
 170 .Fo puffs_node_read
 171 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "uint8_t *buf"
 172 .Fa "off_t offset" "size_t *resid" "const struct puffs_cred *pcr" "int ioflag"
 173 .Fc
 174 .Ft int
 175 .Fo puffs_node_write
 176 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "uint8_t *buf"
 177 .Fa "off_t offset" "size_t *resid" "const struct puffs_cred *pcr" "int ioflag"
 178 .Fc
 179 .Ft int
 180 .Fo puffs_node_abortop
 181 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc"
 182 .Fa "const struct puffs_cn *pcn"
 183 .Fc
 184 .Ft int
 185 .Fo puffs_node_getextattr
 186 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace"
 187 .Fa "const char *attrname" "size_t *attrsize" "uint8_t *attr" "size_t *resid"
 188 .Fa "const struct puffs_cred *pcr"
 189 .Fc
 190 .Ft int
 191 .Fo puffs_node_setextattr
 192 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace"
 193 .Fa "const char *attrname" "uint8_t *attr" "size_t *resid"
 194 .Fa "const struct puffs_cred *pcr"
 195 .Fc
 196 .Ft int
 197 .Fo puffs_node_listextattr
 198 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace"
 199 .Fa "size_t *attrssize" "uint8_t *attrs" "int flag" "size_t *resid"
 200 .Fa "const struct puffs_cred *pcr"
 201 .Fc
 202 .Ft int
 203 .Fo puffs_node_deleteextattr
 204 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc" "int attrnamespace"
 205 .Fa "const char *attrname"
 206 .Fa "const struct puffs_cred *pcr"
 207 .Fc
 208 .Ft int
 209 .Fn puffs_node_print "struct puffs_usermount *pu" "puffs_cookie_t opc"
 210 .Ft int
 211 .Fo puffs_node_reclaim
 212 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc"
 213 .Fc
 214 .Ft int
 215 .Fo puffs_node_inactive
 216 .Fa "struct puffs_usermount *pu" "puffs_cookie_t opc"
 217 .Fc
 218 .Ft void
 219 .Fn puffs_setback "struct puffs_cc *pcc" "int op"
 220 .Ft void
 221 .Fn puffs_newinfo_setcookie "struct puffs_newinfo *pni" "puffs_cookie_t cookie"
 222 .Ft void
 223 .Fn puffs_newinfo_setvtype "struct puffs_newinfo *pni" "enum vtype vtype"
 224 .Ft void
 225 .Fn puffs_newinfo_setsize "struct puffs_newinfo *pni" "voff_t size"
 226 .Sh DESCRIPTION
 227 The operations
 228 .Nm puffs
 229 requires to function can be divided into two categories: file system
 230 callbacks and node callbacks.
 231 The former affect the entire file system while the latter are targeted
 232 at a file or a directory and a file.
 233 They are roughly equivalent to the vfs and vnode operations in the
 234 kernel.
 235 .Pp
 236 All callbacks can be prototyped with the file system name and operation
 237 name using the macro
 238 .Fn PUFFSOP_PROTOS fsname .
 239 .Ss File system callbacks (puffs_fs)
 240 .Bl -tag -width xxxx
 241 .It Fn puffs_fs_statvfs "pu" "sbp"
 242 The following fields of the argument
 243 .Fa sbp
 244 need to be filled:
 245 .Bd -literal
 246  * unsigned long  f_bsize;     file system block size
 247  * unsigned long  f_frsize;    fundamental file system block size
 248  * fsblkcnt_t     f_blocks;    number of blocks in file system,
 249  *                                      (in units of f_frsize)
 250  *
 251  * fsblkcnt_t     f_bfree;     free blocks avail in file system
 252  * fsblkcnt_t     f_bavail;    free blocks avail to non-root
 253  * fsblkcnt_t     f_bresvd;    blocks reserved for root
 254
 255  * fsfilcnt_t     f_files;     total file nodes in file system
 256  * fsfilcnt_t     f_ffree;     free file nodes in file system
 257  * fsfilcnt_t     f_favail;    free file nodes avail to non-root
 258  * fsfilcnt_t     f_fresvd;    file nodes reserved for root
 259
 260 .Ed
 261 .It Fn puffs_fs_sync "pu" "waitfor" "pcr"
 262 All the dirty buffers that have been cached at the file server
 263 level including metadata should be committed to stable storage.
 264 The
 265 .Fa waitfor
 266 parameter affects the operation.
 267 Possible values are:
 268 .Bl -tag -width XMNT_NOWAITX
 269 .It Dv MNT_WAIT
 270 Wait for all I/O for complete until returning.
 271 .It Dv MNT_NOWAIT
 272 Initiate I/O, but do not wait for completion.
 273 .It Dv MNT_LAZY
 274 Synchorize data not synchoronized by the file system syncer,
 275 i.e. data not written when
 276 .Fn puffs_node_fsync
 277 is called with
 278 .Dv FSYNC_LAZY .
 279 .El
 280 .Pp
 281 The credentials for the initiator of the sync operation are present in
 282 .Fa pcr
 283 and will usually be either file system or kernel credentials, but might
 284 also be user credentials.
 285 However, most of the time it is advisable to sync regardless of the
 286 credentials of the caller.
 287 .It Fn puffs_fs_fhtonode "pu" "fid" "fidsize" "pni"
 288 Translates a file handle
 289 .Fa fid
 290 to a node.
 291 The parameter
 292 .Fa fidsize
 293 indicates how large the file handle is.
 294 In case the file system's handles are static length, this parameter can
 295 be ignored as the kernel guarantees all file handles passed to the file
 296 server are of correct length.
 297 For dynamic length handles the field should be examined and
 298 .Er EINVAL
 299 returned in case the file handle length is not correct.
 300 .Pp
 301 This function provides essentially the same information to the kernel as
 302 .Fn puffs_node_lookup .
 303 The information is necessary for creating a new vnode corresponding to
 304 the file handle.
 305 .It Fn puffs_fs_nodetofh "pu" "cookie" "fid" "fidsize"
 306 Create a file handle from the node described by
 307 .Fa cookie .
 308 The file handle should contain enough information to reliably identify
 309 the node even after reboots and the pathname/inode being replaced by
 310 another file.
 311 If this is not possible, it is up to the author of the file system to
 312 act responsibly and decide if the file system can support file handles
 313 at all.
 314 .Pp
 315 For file systems which want dynamic length file handles, this function
 316 must check if the file handle space indicated by
 317 .Fa fidsize
 318 is large enough to accommodate the file handle for the node.
 319 If not, it must fill in the correct size and return
 320 .Er E2BIG .
 321 In either case, the handle length should be supplied to the kernel in
 322 .Fa fidsize .
 323 File systems with static length handles can ignore the size parameter as
 324 the kernel always supplies the correct size buffer.
 325 .It Fn puffs_fs_unmount "pu" "flags"
 326 Unmount the file system.
 327 The kernel has assumedly flushed all cached data when this callback
 328 is executed.
 329 If the file system cannot currently be safely be unmounted, for whatever
 330 reason, the kernel will honor an error value and not forcibly unmount.
 331 However, if the flag
 332 .Dv MNT_FORCE
 333 is not honored by the file server, the kernel will forcibly unmount
 334 the file system.
 335 .El
 336 .Ss Node callbacks
 337 These operations operate in the level of individual files.
 338 The file cookie is always provided as the second argument
 339 .Fa opc .
 340 If the operation is for a file, it will be the cookie of the file.
 341 The case the operation involves a directory (such as
 342 .Dq create file in directory ) ,
 343 the cookie will be for the directory.
 344 Some operations take additional cookies to describe the rest of
 345 the operands.
 346 The return value 0 signals success, else an appropriate errno value
 347 should be returned.
 348 Please note that neither this list nor the descriptions are complete.
 349 .Bl -tag -width xxxx
 350 .It Fn puffs_node_lookup "pu" "opc" "pni" "pcn"
 351 This function is used to locate nodes, or in other words translate
 352 pathname components to file system data structures.
 353 The implementation should match the name in
 354 .Fa pcn
 355 against the existing entries in the directory provided by the cookie
 356 .Fa opc .
 357 If found, the cookie for the located node should be set in
 358 .Fa pni
 359 using
 360 .Fn puffs_newinfo_setcookie .
 361 Additionally, the vnode type and size (latter applicable to regular files only)
 362 should be set using
 363 .Fn puffs_newinfo_setvtype
 364 and
 365 .Fn puffs_newinfo_setsize ,
 366 respectively.
 367 .Pp
 368 The type of operation is found from
 369 .Va pcn-\*[Gt]pcn_nameiop :
 370 .Bl -tag -width XNAMEI_LOOKUPX
 371 .It Dv NAMEI_LOOKUP
 372 Normal lookup operation.
 373 .It Dv NAMEI_CREATE
 374 Lookup to create a node.
 375 .It Dv NAMEI_DELETE
 376 Lookup for node deletion.
 377 .It Dv NAMEI_RENAME
 378 Lookup for the target of a rename operation (source will be looked
 379 up using
 380 .Dv NAMEI_DELETE ) .
 381 .El
 382 .Pp
 383 The final component from a pathname lookup usually requires special
 384 treatment.
 385 It can be identified by looking at the
 386 .Va pcn-\*[Gt]pcn_flags
 387 fields for the flag
 388 .Dv PUFFSLOOKUP_ISLASTCN .
 389 For example, in most cases the lookup operation will want to check if
 390 a delete, rename or create operation has enough credentials to perform
 391 the operation.
 392 .Pp
 393 The return value 0 signals a found node and a nonzero value signals
 394 an errno.
 395 As a special case,
 396 .Er ENOENT
 397 signals "success" for cases where the lookup operation is
 398 .Dv NAMEI_CREATE
 399 or
 400 .Dv NAMEI_RENAME .
 401 Failure in these cases can be signalled by returning another appropriate
 402 error code, for example
 403 .Er EACCESS .
 404 .Pp
 405 Usually a null-terminated string for the next pathname component is
 406 provided in
 407 .Ar pcn-\*[Gt]pcn_name .
 408 In case the file system is using the option
 409 .Dv PUFFS_KFLAG_LOOKUP_FULLPNBUF ,
 410 the remainder of the complete pathname under lookup is found in
 411 the same location.
 412 .Ar pcn-\*[Gt]pcn_namelen
 413 always specifies the length of the next component.
 414 If operating with a full path, the file system is allowed to consume
 415 more than the next component's length in node lookup.
 416 This is done by setting
 417 .Ar pcn-\*[Gt]pcn_consume
 418 to indicate the amount of
 419 .Em extra
 420 characters in addition to
 421 .Ar pcn-\*[Gt]pcn_namelen
 422 processed.
 423 .It Fn puffs_node_create "pu" "opc" "pni" "pcn" "va"
 424 .It Fn puffs_node_mkdir "pu" "opc" "pni" "pcn" "va"
 425 .It Fn puffs_node_mknod "pu" "opc" "pni" "pcn" "va"
 426 A file node is created in the directory denoted by the cookie
 427 .Fa opc
 428 by any of the above callbacks.
 429 The name of the new file can be found from
 430 .Fa pcn
 431 and the attributes are specified by
 432 .Fa va
 433 and the cookie for the newly created node should be set in
 434 .Fa pni .
 435 The only difference between these three is that they create a regular
 436 file, directory and device special file, respectively.
 437 .Pp
 438 In case of mknod, the device identifier can be found in
 439 .Fa va-\*[Gt]va_rdev .
 440 .It Fn puffs_node_open "pu" "opc" "mode" "pcr"
 441 Open the node denoted by the cookie
 442 .Fa opc .
 443 The parameter
 444 .Fa mode
 445 specifies the flags that
 446 .Xr open 2
 447 was called with, e.g.
 448 .Dv O_APPEND
 449 and
 450 .Dv O_NONBLOCK .
 451 .It Fn puffs_node_close "pu" "opc" "flags" "pcr"
 452 Close a node.
 453 The parameter
 454 .Fa flags
 455 parameter describes the flags that the file was opened with.
 456 .It Fn puffs_node_access "pu" "opc" "mode" "pcr"
 457 Check if the credentials of
 458 .Fa pcr
 459 have the right to perform the operation specified by
 460 .Fa mode
 461 onto the node
 462 .Fa opc .
 463 The argument
 464 .Fa mode
 465 can specify read, write or execute by
 466 .Dv PUFFS_VREAD ,
 467 .Dv PUFFS_VWRITE ,
 468 and
 469 .Dv PUFFS_VEXEC ,
 470 respectively.
 471 .It Fn puffs_node_getattr "pu" "opc" "va" "pcr"
 472 The attributes of the node specified by
 473 .Fa opc
 474 must be copied to the space pointed by
 475 .Fa va .
 476 .It Fn puffs_node_setattr "pu" "opc" "va" "pcr"
 477 The attributes for the node specified by
 478 .Fa opc
 479 must be set to those contained in
 480 .Fa va .
 481 Only fields of
 482 .Fa va
 483 which contain a value different from
 484 .Dv PUFFS_VNOVAL
 485 (typecast to the field's type!) contain a valid value.
 486 .It Fn puffs_node_poll "pu" "opc" "events"
 487 Poll for events on node
 488 .Ar opc .
 489 If
 490 .Xr poll 2
 491 events specified in
 492 .Ar events
 493 are available, the function should set the bitmask to match available
 494 events and return immediately.
 495 Otherwise, the function should block (yield) until some events in
 496 .Ar events
 497 become available and only then set the
 498 .Ar events
 499 bitmask and return.
 500 .Pp
 501 In case this function returns an error,
 502 .Dv POLLERR
 503 (or it's
 504 .Xr select 2
 505 equivalent) will be delivered to the calling process.
 506 .Pp
 507 .Em NOTE!
 508 The system call interface for
 509 .Fn poll
 510 contains a timeout parameter.
 511 At this level, however, the timeout is not supplied.
 512 In case input does not arrive, the file system should periodically
 513 unblock and return 0 new events to avoid hanging forever.
 514 This will hopefully be better supported by libpuffs in the future.
 515 .It Fn puffs_node_mmap "pu" "opc" "flags" "pcr"
 516 Called when a regular file is being memory mapped by
 517 .Xr mmap 2 .
 518 .Fa flags
 519 is currently always 0.
 520 .It Fn puffs_node_fsync "pu" "opc" "pcr" "flags" "offlo" "offhi"
 521 Sychronize a node's contents onto stable storage.
 522 This is necessary only if the file server caches some information
 523 before committing it.
 524 The parameter
 525 .Fa flags
 526 specifies the minimum level of sychronization required (XXX: they are
 527 not yet available).
 528 The parameters
 529 .Fa offlo
 530 and
 531 .Fa offhi
 532 specify the data offsets requiring to be synced.
 533 A high offset of 0 means sync from
 534 .Fa offlo
 535 to the end of the file.
 536 .It Fn puffs_node_seek "pu" "opc" "oldoff" "newoff" "pcr"
 537 Test if the node
 538 .Ar opc
 539 is seekable to the location
 540 .Ar newoff .
 541 The argument
 542 .Ar oldoff
 543 specifies the offset we are starting the seek from.
 544 Most file systems dealing only with regular will choose to not
 545 implement this.
 546 However, it is useful for example in cases where files are
 547 unseekable streams.
 548 .It Fn puffs_node_remove "pu" "opc" "targ" "pcn"
 549 .It Fn puffs_node_rmdir "pu" "opc" "targ" "pcn"
 550 Remove the node
 551 .Fa targ
 552 from the directory indicated by
 553 .Fa opc .
 554 The directory entry name to be removed is provided by
 555 .Fa pcn .
 556 The rmdir operation removes only directories, while the remove
 557 operation removes all other types except directories.
 558 .Pp
 559 It is paramount to note that the file system may not remove the
 560 node data structures at this point, only the directory entry and prevent
 561 lookups from finding the node again.
 562 This is to retain the
 563 .Ux
 564 open file semantics.
 565 The data may be removed only when
 566 .Fn puffs_node_reclaim
 567 is called for the node, as this assures there are no further users.
 568 .It Fn puffs_node_link "pu" "opc" "targ" "pcn"
 569 Create a hard link for the node
 570 .Fa targ
 571 into the directory
 572 .Fa opc .
 573 The argument
 574 .Fa pcn
 575 provides the directory entry name for the new link.
 576 .It Fn puffs_node_rename "pu" "src_dir" "src" "pcn_src" "targ_dir" "targ" "pcn_targ"
 577 Rename the node
 578 .Fa src
 579 with the name specified by
 580 .Fa pcn_src
 581 from the directory
 582 .Fa src_dir .
 583 The target directory and target name are given by
 584 .Fa targ_dir
 585 and
 586 .Fa pcn_targ ,
 587 respectively.
 588 .Em If
 589 the target node already exists, it is specified by
 590 .Fa targ
 591 and must be replaced atomically.
 592 Otherwise
 593 .Fa targ
 594 is gives as
 595 .Dv NULL .
 596 .Pp
 597 It is legal to replace a directory node by another directory node with
 598 the means of rename if the target directory is empty, otherwise
 599 .Er ENOTEMPTY
 600 should be returned.
 601 All other types can replace all other types.
 602 In case a rename between incompatible types is attempted, the errors
 603 .Er ENOTDIR
 604 or
 605 .Er EISDIR
 606 should be returned, depending on the target type.
 607 .It Fn puffs_node_readdir "pu" "opc" "dent" "readoff" "reslen" "pcr" "eofflag" "cookies" "ncookies"
 608 To read directory entries,
 609 .Fn puffs_node_readdir
 610 is called.
 611 It should store directories as
 612 .Va struct dirent
 613 in the space pointed to by
 614 .Fa dent .
 615 The amount of space available is given by
 616 .Fa reslen
 617 and before returning it should be set to the amount of space
 618 .Em remaining
 619 in the buffer.
 620 The argument
 621 .Fa offset
 622 is used to specify the offset to the directory.
 623 Its interpretation is up to the file system and it should be set to
 624 signal the continuation point when there is no more room for the next
 625 entry in
 626 .Fa dent .
 627 It is most performant to return the maximal amount of directory
 628 entries each call.
 629 It is easiest to generate directory entries by using
 630 .Fn puffs_nextdent ,
 631 which also automatically advances the necessary pointers.
 632 .Pp
 633 In case end-of-directory is reached,
 634 .Fa eofflag
 635 should be set to one.
 636 Note that even a new call to readdir may start where
 637 .Fa readoff
 638 points to end-of-directory.
 639 .Pp
 640 If the file system supports file handles, the arguments
 641 .Fa cookies
 642 and
 643 .Fa ncookies
 644 must be filled out.
 645 .Fa cookies
 646 is a vector for offsets corresponding to read offsets.
 647 One cookie should be filled out for each directory entry.
 648 The value of the cookie should equal the offset of the
 649 .Em next
 650 directory entry, i.e. which offset should be passed to readdir for
 651 the first entry read to be the entry following the current one.
 652 .Fa ncookies
 653 is the number of slots for cookies in the cookie vector upon entry to
 654 the function and must be set to the amount of cookies stored in the
 655 vector (i.e. amount of directory entries read) upon exit.
 656 There is always enough space in the cookie vector for the maximal number
 657 of entries that will fit into the directory entry buffer.
 658 For filling out the vector, the helper function
 659 .Fn PUFFS_STORE_DCOOKIE cookies ncookies offset
 660 can be used.
 661 This properly checks against
 662 .Fa cookies
 663 being
 664 .Dv NULL .
 665 Note that
 666 .Fa ncookies
 667 must be initialized to zero before the first call to
 668 .Fn PUFFS_STORE_DCOOKIE .
 669 .It Fn puffs_node_symlink "pu" "opc" "pni" "pcn_src" "va" "link_target"
 670 Create a symbolic link into the directory
 671 .Fa opc
 672 with the name in
 673 .Fa pcn_src
 674 and the initial attributes in
 675 .Fa va .
 676 The argument
 677 .Ar link_target
 678 contains a null-terminated string for the link target.
 679 The created node cookie should be set in
 680 .Fa pni .
 681 .It Fn puffs_node_readlink "pu" "opc" "pcr" "link" "linklen"
 682 Read the target of a symbolic link
 683 .Fa opc .
 684 The result is placed in the buffer pointed to by
 685 .Fa link .
 686 This buffer's length is given in
 687 .Fa linklen
 688 and it must be updated to reflect the real link length.
 689 A terminating nul character should not be put into the buffer and
 690 .Em "must not"
 691 be included in the link length.
 692 .It Fn puffs_node_read "pu" "opc" "buf" "offset" "resid" "pcr" "ioflag"
 693 Read the contents of a file
 694 .Fa opc .
 695 It will gather the data from
 696 .Fa offset
 697 in the file and read the number
 698 .Fa resid
 699 octets.
 700 The buffer is guaranteed to have this much space.
 701 The amount of data requested by
 702 .Fa resid
 703 should be read, except in the case of eof-of-file or an error.
 704 The parameter
 705 .Fa resid
 706 should be set to indicate the amount of request NOT completed.
 707 In the normal case this should be 0.
 708 .It Fn puffs_node_write "pu" "opc" "buf" "offset" "resid" "pcr" "ioflag"
 709 .Fn puffs_node_write
 710 Write data to a file
 711 .Fa opc
 712 at
 713 .Fa offset
 714 and extend the file if necessary.
 715 The number of octets written is indicated by
 716 .Fa resid ;
 717 everything must be written or an error will be generated.
 718 The parameter must be set to indicate the amount of data NOT written.
 719 In case the flag
 720 .Dv PUFFS_IO_APPEND
 721 is specified, the data should be appended to the end of the file.
 722 .It Fn puffs_node_print "pu" "opc"
 723 Print information about node.
 724 This is used only for kernel-initiated diagnostic purposes.
 725 .It Fn puffs_node_reclaim "pu" "opc"
 726 The kernel will no longer reference the cookie and resources associated
 727 with it may be freed.
 728 In case the file
 729 .Fa opc
 730 has a link count of zero, it may be safely removed now.
 731 .It Fn puffs_node_abortop "pu" "opc" "pcn"
 732 In case the operation following lookup (e.g. mkdir or remove) is not
 733 executed for some reason, abortop will be issued.
 734 This is useful only for servers which cache state between lookup
 735 and a directory operation and is generally left unimplemented.
 736 .It Fn puffs_node_inactive "pu" "opc"
 737 The node
 738 .Fa opc
 739 has lost its last reference in the kernel.
 740 However, the cookie must still remain valid until
 741 .Fn puffs_node_reclaim
 742 is called.
 743 .It Fn puffs_setback "pcc" "op"
 744 Issue a "setback" operation which will be handled when the request response
 745 is returned to the kernel.
 746 Currently this can be only called from mmap, open, remove and rmdir.
 747 The valid parameters for
 748 .Ar op
 749 are
 750 .Dv PUFFS_SETBACK_INACT_N1
 751 and
 752 .Dv PUFFS_SETBACK_INACT_N2 .
 753 These signal that a file system mounted with
 754 .Dv PUFFS_KFLAG_IAONDEMAND
 755 should call the file system inactive method for the specified node.
 756 The node number 1 always means the operation cookie
 757 .Ar opc ,
 758 while the node number 2 can be used to specify the second node argument
 759 present in some methods, e.g. remove.
 760 .It Fn puffs_newinfo_setcookie pni cookie
 761 Set cookie for node provided by this method to
 762 .Ar cookie .
 763 .It Fn puffs_newinfo_setvtype pni vtype
 764 Set the type of the newly located node to
 765 .Ar vtype .
 766 This call is valid only for
 767 .Fn lookup
 768 and
 769 .Fn fhtonode .
 770 .It Fn puffs_newinfo_setsize pni size
 771 Set the size of the newly located node to
 772 .Ar size .
 773 If left unset, the value defaults to 0.
 774 This call is valid only for
 775 .Fn lookup
 776 and
 777 .Fn fhtovp .
 778 .El
 779 .Sh SEE ALSO
 780 .Xr puffs 3
 781 .\".Xr vfsops 9 ,
 782 .\".Xr vnodeops 9