summaryrefslogtreecommitdiff
path: root/share/man/man9/VOP_LOOKUP.9
blob: af1a8d2c7305bcf385f68f25eeb7fb892c85edf7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
.\" $OpenBSD: VOP_LOOKUP.9,v 1.21 2009/05/21 12:24:22 thib Exp $
.\"
.\" Copyright (c) 2003 Ted Unangst
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: May 21 2009 $
.Dt VOP_LOOKUP 9
.Os
.Sh NAME
.Nm VOP_LOOKUP
.Nd vnode operations
.Sh SYNOPSIS
.Fd #include <sys/vnode.h>
.Ft int
.Fo VOP_ABORTOP
.Fa "struct vnode *dvp"
.Fa "struct componentname *cnp"
.Fc
.Ft int
.Fo VOP_ACCESS
.Fa "struct vnode *vp"
.Fa "int mode"
.Fa "struct ucred *cred"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_ADVLOCK
.Fa "struct vnode *vp"
.Fa "void *id"
.Fa "int op"
.Fa "struct flock *fl"
.Fa "int flags"
.Fc
.Ft int
.Fo VOP_BMAP
.Fa "struct vnode *vp"
.Fa "daddr64_t bn"
.Fa "struct vnode **vpp"
.Fa "daddr64_t *bnp"
.Fa "int *runp"
.Fc
.Ft int
.Fo VOP_BWRITE
.Fa "struct buf *bp"
.Fc
.Ft int
.Fo VOP_CLOSE
.Fa "struct vnode *vp"
.Fa "int fflag"
.Fa "struct ucred *cred"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_CREATE
.Fa "struct vnode *dvp"
.Fa "struct vnode **vpp"
.Fa "struct componentname *cnp"
.Fa "struct vattr *vap"
.Fc
.Ft int
.Fo VOP_FSYNC
.Fa "struct vnode *vp"
.Fa "struct ucred *cred"
.Fa "int waitfor"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_GETATTR
.Fa "struct vnode *vp"
.Fa "struct vattr *vap"
.Fa "struct ucred *cred"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_INACTIVE
.Fa "struct vnode *vp"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_IOCTL
.Fa "struct vnode *vp"
.Fa "u_long command"
.Fa "void *data"
.Fa "int fflag"
.Fa "struct ucred *cred"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_ISLOCKED
.Fa "struct vnode *vp"
.Fc
.Ft int
.Fo VOP_KQFILTER
.Fa "struct vnode *vp"
.Fa "struct knote *kn"
.Fc
.Ft int
.Fo VOP_LINK
.Fa "struct vnode *dvp"
.Fa "struct vnode *vp"
.Fa "struct componentname *cnp"
.Fc
.Ft int
.Fo VOP_LOCK
.Fa "struct vnode *vp"
.Fa "int flags"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_LOOKUP
.Fa "struct vnode *dvp"
.Fa "struct vnode **vpp"
.Fa "struct componentname *cnp"
.Fc
.Ft int
.Fo VOP_MKDIR
.Fa "struct vnode *dvp"
.Fa "struct vnode **vpp"
.Fa "struct componentname *cnp"
.Fa "struct vattr *vap"
.Fc
.Ft int
.Fo VOP_MKNOD
.Fa "struct vnode *dvp"
.Fa "struct vnode **vpp"
.Fa "struct componentname *cnp"
.Fa "struct vattr *vap"
.Fc
.Ft int
.Fo VOP_OPEN
.Fa "struct vnode *vp"
.Fa "int mode"
.Fa "struct ucred *cred"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_PATHCONF
.Fa "struct vnode *vp"
.Fa "int name"
.Fa "register_t *retval"
.Fc
.Ft int
.Fo VOP_POLL
.Fa "struct vnode *vp"
.Fa "int events"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_PRINT
.Fa "struct vnode *vp"
.Fc
.Ft int
.Fo VOP_READ
.Fa "struct vnode *vp"
.Fa "struct uio *uio"
.Fa "int ioflag"
.Fa "struct ucred *cred"
.Fc
.Ft int
.Fo VOP_READDIR
.Fa "struct vnode *vp"
.Fa "struct uio *uio"
.Fa "struct ucred *cred"
.Fa "int *eofflag"
.Fa "int *ncookies"
.Fa "u_long **cookies"
.Fc
.Ft int
.Fo VOP_READLINK
.Fa "struct vnode *vp"
.Fa "struct uio *uio"
.Fa "struct ucred *cred"
.Fc
.Ft int
.Fo VOP_REALLOCBLKS
.Fa "struct vnode *vp"
.Fa "struct cluster_save *buflist"
.Fc
.Ft int
.Fo VOP_RECLAIM
.Fa "struct vnode *vp"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_REMOVE
.Fa "struct vnode *dvp"
.Fa "struct vnode *vp"
.Fa "struct componentname *cnp"
.Fc
.Ft int
.Fo VOP_RENAME
.Fa "struct vnode *fdvp"
.Fa "struct vnode *fvp"
.Fa "struct componentname *fcnp"
.Fa "struct vnode *tdvp"
.Fa "struct vnode *tvp"
.Fa "struct componentname *tcnp"
.Fc
.Ft int
.Fo VOP_REVOKE
.Fa "struct vnode *vp"
.Fa "int flags"
.Fc
.Ft int
.Fo VOP_RMDIR
.Fa "struct vnode *dvp"
.Fa "struct vnode *vp"
.Fa "struct componentname *cnp"
.Fc
.Ft int
.Fo VOP_SETATTR
.Fa "struct vnode *vp"
.Fa "struct vattr *vap"
.Fa "struct ucred *cred"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_STRATEGY
.Fa "struct buf *bp"
.Fc
.Ft int
.Fo VOP_SYMLINK
.Fa "struct vnode *dvp"
.Fa "struct vnode **vpp"
.Fa "struct componentname *cnp"
.Fa "struct vattr *vap"
.Fa "char *target"
.Fc
.Ft int
.Fo VOP_UNLOCK
.Fa "struct vnode *vp"
.Fa "int flags"
.Fa "struct proc *p"
.Fc
.Ft int
.Fo VOP_WRITE
.Fa "struct vnode *vp"
.Fa "struct uio *uio"
.Fa "int ioflag"
.Fa "struct ucred *cred"
.Fc
.Sh DESCRIPTION
The
.Nm VOP
functions implement a generic way to perform operations on vnodes.
The VOP function called passes the arguments to the correct file system
specific function.
Not all file systems implement all operations, in which case a generic
method will be used.
These functions exist to provide an abstract method to invoke vnode
operations without needing to know anything about the underlying file system.
Many system calls map directly to a specific VOP function.
.Pp
The arguments for each VOP
function consist of one or more vnode pointers along with other data
needed to perform the operation.
Care must be taken to obey the vnode locking discipline when using
VOP functions.
The locking discipline for all currently defined VOP
functions is described in the file
.Pa sys/kern/vnode_if.src .
Many VOP calls take a
.Vt struct proc *p
argument.
This should be the current process.
VOP calls are not safe to call in an interrupt context.
.Pp
The following sections comment on the VOP functions from the consumer's
perspective.
Some notes for file system implementors follow.
.Pp
.Bl -tag -width Ds -compact
.It Fn VOP_ABORTOP dvp cnp
Abort any asynchronous operations pending on the vnode
.Fa dvp
associated with the path name
.Fa cnp .
This is mostly used by internal VFS code and should not be needed by
file system implementors.
.Pp
.It Fn VOP_ACCESS vp mode cred p
Determine if the locked vnode
.Fa vp
can be accessed by the calling process
.Fa p
with credentials
.Fa cred
for the given access
.Fa mode .
.Pp
.Fa mode
may contain any of the following values:
.Pp
.Bl -tag -width Ds -compact -offset indent
.It Dv VWRITE
check writeability
.It Dv VREAD
check readability
.It Dv VEXEC
check executability
.El
.Pp
If the access check succeeds, zero is returned; otherwise, an
appropriate error code is returned.
.Pp
.It Fn VOP_ADVLOCK vp id op fl flags
Perform advisory locking on the vnode
.Fa vp
according to the operation
.Fa op
and lock specification
.Fa fl .
.Fa id
identifies the resource holding the lock
(typically a pointer to the holding process).
.Pp
.Fa op
may be one of the following operations:
.Pp
.Bl -tag -width F_GETLK -compact -offset indent
.It Dv F_GETLK
Get the first lock that would block a lock request.
.It Dv F_SETLK
Set a lock.
.It Dv F_UNLCK
Release a lock.
.El
.Pp
.Fa flags
may contain the following flags:
.Pp
.Bl -tag -width F_POSIX -compact -offset indent
.It Dv F_WAIT
If required, block waiting to obtain an exclusive lock.
.It Dv F_POSIX
Follow
.Tn POSIX
locking semantics; see
.Xr fcntl 2 .
.It Dv F_FLOCK
Follow
.Xr flock 2
locking semantics.
.El
.Pp
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_BMAP vp bn vpp bnp runp
Convert the logical block number
.Fa bn
of the file the locked vnode
.Fa vp
is associated with to its physical number on-disk.
The physical block number is stored in
.Fa *bnp
on return.
.Fa vpp ,
if
.No non- Ns Dv NULL ,
will be updated to point to the vnode of the block device of which
.Fa vp
is associated.
.Fa runp ,
if
.No non- Ns Dv NULL ,
will be updated to the number of contiguous disk blocks following
.Fa *bnp .
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_BWRITE bp
Write a file system buffer to disk.
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_CLOSE vp fflag cred p
Close the file associated with the locked vnode
.Fa vp
with file flags
.Fa fflag
by the calling process
.Fa p
with credentials
.Fa cred .
This operation should be performed only when the file is no longer being
used.
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_CREATE dvp vpp cnp vap
Create a new directory entry for a regular file in the directory
.Fa dvp
and return a locked, referenced vnode in
.Fa vpp .
The file name is in
.Fa cnp
and its permissions will be
.Fa vap .
.Pp
.It Fn VOP_FSYNC vp cred waitfor p
Flush any dirty buffers associated with
.Fa vp
to disk.
The vnode is locked on entry and exit.
.Fa waitfor
can be set to
.Dv MNT_WAIT
to indicate that
.Fn VOP_FSYNC
should not return until all data is written.
.Pp
.It Fn VOP_GETATTR vp vap cred p
.It Fn VOP_SETATTR vp vap cred p
Access the vnode attributes
.Fa vap
of the vnode
.Fa vp
by the calling process
.Fa p
with credentials
.Fa cred .
.Fn VOP_SETATTR
requires that
.Fa vp
be locked.
A field value for any member of
.Fa vap
of
.Dv VNOVAL
represents that the information could not be obtained by
.Fn VOP_GETATTR
or should not be changed by
.Fn VOP_SETATTR .
Upon success of obtaining or changing the attributes, zero is returned;
otherwise, an appropriate error code is returned.
.Pp
.It Fn VOP_INACTIVE vp p
Notify the underlying file system that the locked vnode
.Fa vp
is no longer in use.
The vnode will be unlocked upon return.
.Fa p
specifies the calling process.
This may happen when the vnode reference count reaches zero or
when the underlying file system has disappeared or has been forcibly
unmounted.
.Pp
Typically, the underlying file system will write any buffers associated
with
.Fa vp
to disk or delete the file entry, if need be.
The underlying file system may not necessarily release any buffers
associated with
.Fa vp
so that it can be immediately reactivated in case the file is used again.
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_IOCTL vp command data fflag cred p
Perform the control operation
.Fa command
with additional information
.Fa data
on the vnode
.Fa vp ,
normally associated with a device,
with file flags
.Fa fflag
by the calling process
.Fa p
with credentials
.Fa cred .
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_ISLOCKED vp
.It Fn VOP_LOCK vp flags p
.It Fn VOP_UNLOCK vp flags p
.Fn VOP_LOCK
is used internally by
.Xr vn_lock 9
to lock a vnode.
It should not be used by other file system code.
.Fn VOP_UNLOCK
unlocks a vnode.
.Fa flags
should be zero in most cases.
.Fn VOP_ISLOCKED
returns 1 if
.Fa vp
is locked and 0 if not.
It should be used cautiously, as not all file systems implement locks
effectively.
Note the asymmetry between
.Xr vn_lock 9
and
.Fn VOP_UNLOCK .
.Pp
.It Fn VOP_KQFILTER vp kn
Register the
.Xr knote 9
filtering information
.Fa kn
for the vnode
.Fa vp .
Only filters for
.Dv EVFILT_READ ,
.Dv EVFILT_WRITE ,
and
.Dv EVFILT_VNODE
will invoke this operation.
Upon success, zero is returned; otherwise, a non-zero value is returned.
.Pp
.It Fn VOP_LINK dvp vp cnp
Increase the link count for the vnode
.Fa vp .
A new entry with name
.Fa cnp
should be added to the directory
.Fa dvp .
.Fa dvp
is locked on entry and unlocked on exit.
.Pp
.It Fn VOP_LOOKUP dvp vpp cnp
Find the file corresponding to the name
.Fa cnp
in the directory
.Fa dvp
and return a vnode in
.Fa vpp .
.Fa dvp
is locked on entry and exit, and
.Fa vpp
is locked upon a successful return.
.Fa vpp
will be
.Dv NULL
on error, and
.Fa cnp->cn_flags
will be set to
.Dv PDIRUNLOCK
if
.Fa dvp
has been unlocked for an unsuccessful return.
.Pp
.It Fn VOP_MKDIR dvp vpp cnp vap
Create a new directory named by
.Fa cnp
with permissions
.Fa vattr
in the directory
.Fa dvp .
On success, the new vnode is returned locked in
.Fa vpp .
.Fa dvp
must be locked on entry and is unlocked on exit.
.Pp
.It Fn VOP_MKNOD dvp vpp cnp vap
Create a device special file with name
.Fa cnp
and attributes
.Fa vap
in the directory associated with the locked vnode
.Fa dvp .
.Fa dvp
will be unlocked on return (see
.Xr vput 9 ) .
A pointer to the new, locked vnode will be returned in
.Fa *vpp
if
.Fa vpp
is not
.Dv NULL .
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_OPEN vp mode cred p
Open the file associated with the vnode
.Fa vp
with the access modes
.Fa mode
by the calling process
.Fa p
with credentials
.Fa cred .
.Fa mode
takes the flags described in
.Xr open 2 .
.Pp
For some underlying file systems, access permissions for the file by the
process are checked; for others, this is a no-op.
In any case, this must be called before a process can access the file.
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_PATHCONF vp name retval
Obtain the value of the applicable
.Tn POSIX
configurable pathname variable (see
.Xr pathconf 2 )
specified by
.Fa name
from the locked vnode
.Fa vp .
The result is placed in
.Fa *retval .
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_POLL vp events p
Determine whether the vnode
.Fa vp
is ready to perform the operations specified by
.Fa events
(see
.Xr poll 2 )
for the calling process
.Fa p .
The
.Fn selrecord
routine may be used to detect selection collisions for multiple
processes sleeping on the same file, waiting for
.Tn I/O
to become possible, although all file systems currently assume that
.Tn I/O
is always possible.
The return value specifies which operations from
.Fa events
were found to be ready, which may be performed without the need for
blocking.
.Pp
.It Fn VOP_PRINT vp
Print information about the vnode to the kernel message buffer.
It is not used normally, but exists only for debugging purposes.
.Pp
.It Fn VOP_READ vp uio ioflag cred
Copy data from the locked vnode
.Fa vp
to the buffers specified by
.Fa uio
with calling process credentials
.Fa cred .
.Pp
.Fa ioflag
may contain the following flags:
.Pp
.Bl -tag -width IO_APPEND -offset indent -compact
.It Dv IO_NDELAY
Non-blocking I/O.
.It Dv IO_UNIT
Do I/O as an atomic unit.
.El
.Pp
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_READDIR vp uio cred eofflag ncookies cookies
Read the contents of the directory associated with the locked vnode
.Fa vp ,
usually via
.Fn VOP_READ ,
and convert its file-system-specific format to that expected by the
.Xr getdirentries 2
system call, storing the result into the buffers specified by
.Fa uio .
.Fa cred
specifies the credentials of the calling process.
.Fa *eofflag
is set to a non-zero value on return once successful end-of-file for the
directory contents has been reached.
.Pp
.Fa ncookies
and
.Fa cookies ,
if not
.Dv NULL ,
are used for keeping track of directory seeking.
This is used by some file systems, such as
.Tn NFS ,
to allow sequential chunks of the directory contents to be obtained.
.Pp
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_READLINK vp uio cred
Read a symbolic link and return the target's name in
.Fa uio .
.Fa vp
is locked on entry and exit and must be a symlink.
.Pp
.It Fn VOP_REALLOCBLKS vp buflist
Called by the VFS write clustering code.
It gives the file system an opportunity to rearrange the on-disk blocks
for a file to reduce fragmentation.
.Fa vp
is the locked vnode for the file, and
.Fa buflist
is a cluster of the outstanding buffers about to be written.
Currently, only FFS implements this call.
.Pp
.It Fn VOP_RECLAIM vp p
Used by
.Xr vclean 9
so that the file system has an opportunity to free memory
and perform any other cleanup activity related to
.Fa vp .
.Fa vp
is unlocked on entry and exit.
.Fn VOP_RECLAIM
should not be used by generic code.
.Pp
.It Fn VOP_REMOVE dvp vp cnp
Remove the link named
.Fa cnp
from the directory
.Fa dvp .
This file corresponds to the vnode
.Fa vp .
Both
.Fa dvp
and
.Fa vp
are locked on entry and unlocked on exit, and
each has its reference count decremented by one.
.Fn VOP_REMOVE
does not delete the file from disk unless its link count
becomes zero (for file systems which support multiple links).
.Pp
.It Fn VOP_RENAME fdvp fvp fcnp tdvp tvp tcnp
Remove the link to the file with associated vnode
.Fa fvp
and name
.Fa fcnp
in the directory with associated vnode
.Fa fdvp ,
and create a new link to the file with name
.Fa tcnp
(and associated locked vnode
.Fa tvp ,
if the file already exists) residing in the directory with the
associated locked vnode
.Fa tdvp .
.Fa fdvp ,
.Fa fvp ,
and
.Fa tvp
(if not
.Dv NULL )
will be released (see
.Xr vrele 9 )
and
.Fa tdvp
will have its reference count decremented (see
.Xr vput 9 )
on return.
If not
.Dv NULL ,
.Fa tvp
will be locked on return as well.
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.Pp
.It Fn VOP_REVOKE vp flags
Used by the
.Xr revoke 2
system call to prevent any further access to a vnode.
The vnode ops will be changed to those of deadfs, which returns only
errors.
.Ar vp
must be unlocked.
.Pp
.It Fn VOP_RMDIR dvp vp cnp
Remove the directory
.Fa vp
from the directory
.Fa dvp .
Both are locked on entry and unlocked on exit.
The name of the directory for removal is additionally contained in
.Fa cnp .
.Pp
.It Fn VOP_STRATEGY bp
Call the appropriate strategy function for the device backing the
buffer's vnode.
.Pp
.It Fn VOP_SYMLINK dvp vpp cnp vap target
Create a symbolic link with name
.Fa cnp
in the directory
.Fa dvp
with mode
.Fa vap .
The link will point to
.Fa target
and a vnode for it is returned in
.Fa vpp .
The directory vnode is locked on entry and unlocked on exit.
Note that unlike most VOP calls returning a vnode,
.Fn VOP_SYMLINK
does not lock or reference
.Fa vpp .
.Pp
.It Fn VOP_WRITE vp uio ioflag cred
Copy data from the buffers specified by
.Fa uio
to the locked vnode
.Fa vp
with calling process credentials
.Fa cred .
.Pp
.Fa ioflag
may contain the following flags:
.Pp
.Bl -tag -width IO_APPEND -offset indent -compact
.It Dv IO_APPEND
Perform write at the end of file.
.It Dv IO_NDELAY
Non-blocking I/O.
.It Dv IO_SYNC
Wait for I/O to complete.
.It Dv IO_UNIT
Do I/O as an atomic unit.
.El
.Pp
Upon success, zero is returned; otherwise, an appropriate error code is
returned.
.El
.Sh IMPLEMENTATION NOTES
The
.Nm VOP
functions are stubs which redirect their arguments to the
appropriate function for each file system.
In order to allow for layered file systems and generic bypass methods,
all vnode operation implementing functions take only a single
.Vt void *
pointer as an argument.
This points to a structure containing the real arguments.
Additionally, this structure contains a
.Vt struct vnodeop_desc * ,
or
.Em vnodeop description .
The description is typically used by the abstract VOP code, but can
be useful to the lower implementation as well.
Every file system defines an array of
.Vt struct vnodeopv_entry_desc
that contains one entry for each implemented vnode op.
Unimplemented vnode operations match the default description,
.Va vop_default_desc .
Most non-layer file systems should assign the default error handler,
.Fn vn_default_error ,
to the generic description.
.Pp
All lower level implementations should conform to the interfaces described
above.
The rules for locking and referencing vnodes are enforced by each
file system implementation, not the VOP stubs.
.Sh RETURN VALUES
The
.Nm VOP
functions return 0 to indicate success and a non-zero error code
to indicate failure.
.Sh FILES
.Bl -tag -width sys/kern/vnode_if.src -compact
.It Pa sys/kern/vnode_if.src
source file containing
.Nm VOP
definitions
.It Pa sys/kern/vnode_if.c
C file with implementations of each
.Nm VOP
stub call
.El
.Sh SEE ALSO
.Xr errno 2 ,
.Xr uio 9 ,
.Xr vfs 9 ,
.Xr vn_lock 9 ,
.Xr vnode 9
.Sh AUTHORS
This man page was written by Ted Unangst for
.Ox .
.Sh BUGS
The locking discipline is too complex.
Refer to
.Xr vn_lock 9 .