| 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" "iint 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 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 |