f8b627e940c27c65d7a8fd34a3cdb050d5e82525
[dragonfly.git] / 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" "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 intepretation 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