1.\" $NetBSD: vnodeops.9,v 1.81 2011/06/14 00:22:45 rmind Exp $ 2.\" 3.\" Copyright (c) 2001, 2005, 2006 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Gregory McGarry. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd June 14, 2011 31.Dt VNODEOPS 9 32.Os 33.Sh NAME 34.Nm vnodeops , 35.Nm VOP_LOOKUP , 36.Nm VOP_CREATE , 37.Nm VOP_MKNOD , 38.Nm VOP_OPEN , 39.Nm VOP_CLOSE , 40.Nm VOP_ACCESS , 41.Nm VOP_GETATTR , 42.Nm VOP_SETATTR , 43.Nm VOP_READ , 44.Nm VOP_WRITE , 45.Nm VOP_IOCTL , 46.Nm VOP_FCNTL , 47.Nm VOP_POLL , 48.Nm VOP_KQFILTER , 49.Nm VOP_REVOKE , 50.Nm VOP_MMAP , 51.Nm VOP_FSYNC , 52.Nm VOP_SEEK , 53.Nm VOP_REMOVE , 54.Nm VOP_LINK , 55.Nm VOP_RENAME , 56.Nm VOP_MKDIR , 57.Nm VOP_RMDIR , 58.Nm VOP_SYMLINK , 59.Nm VOP_READDIR , 60.Nm VOP_READLINK , 61.Nm VOP_ABORTOP , 62.Nm VOP_INACTIVE , 63.Nm VOP_RECLAIM , 64.Nm VOP_LOCK , 65.Nm VOP_UNLOCK , 66.Nm VOP_ISLOCKED , 67.Nm VOP_BMAP , 68.Nm VOP_PRINT , 69.Nm VOP_PATHCONF , 70.Nm VOP_ADVLOCK , 71.Nm VOP_WHITEOUT , 72.Nm VOP_GETPAGES , 73.Nm VOP_PUTPAGES , 74.Nm VOP_STRATEGY , 75.Nm VOP_BWRITE , 76.Nm VOP_GETEXTATTR , 77.Nm VOP_SETEXTATTR , 78.Nm VOP_LISTEXTATTR , 79.Nm VOP_DELETEEXTATTR 80.Nd vnode operations 81.Sh SYNOPSIS 82.In sys/param.h 83.In sys/buf.h 84.In sys/dirent.h 85.In sys/vnode.h 86.In sys/mount.h 87.In sys/namei.h 88.In sys/unistd.h 89.In sys/fcntl.h 90.In sys/lockf.h 91.In sys/extattr.h 92.Ft int 93.Fn VOP_LOOKUP "struct vnode *dvp" "struct vnode **vpp" \ 94"struct componentname *cnp" 95.Ft int 96.Fn VOP_CREATE "struct vnode *dvp" "struct vnode **vpp" \ 97"struct componentname *cnp" "struct vattr *vap" 98.Ft int 99.Fn VOP_MKNOD "struct vnode *dvp" "struct vnode **vpp" \ 100"struct componentname *cnp" "struct vattr *vap" 101.Ft int 102.Fn VOP_OPEN "struct vnode *vp" "int mode" "kauth_cred_t cred" 103.Ft int 104.Fn VOP_CLOSE "struct vnode *vp" "int fflag" "kauth_cred_t cred" 105.Ft int 106.Fn VOP_ACCESS "struct vnode *vp" "int mode" "kauth_cred_t cred" 107.Ft int 108.Fn VOP_GETATTR "struct vnode *vp" "struct vattr *vap" "kauth_cred_t cred" 109.Ft int 110.Fn VOP_SETATTR "struct vnode *vp" "struct vattr *vap" "kauth_cred_t cred" 111.Ft int 112.Fn VOP_READ "struct vnode *vp" "struct uio *uio" "int ioflag" \ 113"kauth_cred_t cred" 114.Ft int 115.Fn VOP_WRITE "struct vnode *vp" "struct uio *uio" "int ioflag" \ 116"kauth_cred_t cred" 117.Ft int 118.Fn VOP_IOCTL "struct vnode *vp" "u_long command" "void *data" \ 119"int fflag" "kauth_cred_t cred" 120.Ft int 121.Fn VOP_FCNTL "struct vnode *vp" "u_int command" "void *data" \ 122"int fflag" "kauth_cred_t cred" 123.Ft int 124.Fn VOP_POLL "struct vnode *vp" "int events" 125.Ft int 126.Fn VOP_KQFILTER "struct vnode *vp" "struct knote *kn" 127.Ft int 128.Fn VOP_REVOKE "struct vnode *vp" "int flags" 129.Ft int 130.Fn VOP_MMAP "struct vnode *vp" "vm_prot_t prot" "kauth_cred_t cred" 131.Ft int 132.Fn VOP_FSYNC "struct vnode *vp" "kauth_cred_t cred" "int flags" \ 133"off_t offlo" "off_t offhi" 134.Ft int 135.Fn VOP_SEEK "struct vnode *vp" "off_t oldoff" "off_t newoff" \ 136"kauth_cred_t cred" 137.Ft int 138.Fn VOP_REMOVE "struct vnode *vp" "struct vnode *vp" \ 139"struct componentname *cnp" 140.Ft int 141.Fn VOP_LINK "struct vnode *dvp" "struct vnode *vp" \ 142"struct componentname *cnp" 143.Ft int 144.Fn VOP_RENAME "struct vnode *fdvp" "struct vnode *fvp" \ 145"struct componentname *fcnp" "struct vnode *tdvp" \ 146"struct vnode *tvp" "struct componentname *tcnp" 147.Ft int 148.Fn VOP_MKDIR "struct vnode *dvp" "struct vnode **vpp" \ 149"struct componentname *cnp" "struct vattr *vap" 150.Ft int 151.Fn VOP_RMDIR "struct vnode *dvp" "struct vnode *vp" \ 152"struct componentname *cnp" 153.Ft int 154.Fn VOP_SYMLINK "struct vnode *dvp" "struct vnode **vpp" \ 155"struct componentname *cnp" "struct vattr *vap" "char *target" 156.Ft int 157.Fn VOP_READDIR "struct vnode *vp" "struct uio *uio" \ 158"kauth_cred_t cred" "int *eofflag" "off_t **cookies" "int *ncookies" 159.Ft int 160.Fn VOP_READLINK "struct vnode *vp" "struct uio *uio" "kauth_cred_t cred" 161.Ft int 162.Fn VOP_ABORTOP "struct vnode *dvp" "struct componentname *cnp" 163.Ft int 164.Fn VOP_INACTIVE "struct vnode *vp" 165.Ft int 166.Fn VOP_RECLAIM "struct vnode *vp" 167.Ft int 168.Fn VOP_LOCK "struct vnode *vp" "int flags" 169.Ft int 170.Fn VOP_UNLOCK "struct vnode *vp" 171.Ft int 172.Fn VOP_ISLOCKED "struct vnode *vp" 173.Ft int 174.Fn VOP_BMAP "struct vnode *vp" "daddr_t bn" "struct vnode **vpp" \ 175"daddr_t *bnp" "int *runp" 176.Ft int 177.Fn VOP_PRINT "struct vnode *vp" 178.Ft int 179.Fn VOP_PATHCONF "struct vnode *vp" "int name" "register_t *retval" 180.Ft int 181.Fn VOP_ADVLOCK "struct vnode *vp" "void *id" "int op" \ 182"struct flock *fl" "int flags" 183.Ft int 184.Fn VOP_WHITEOUT "struct vnode *dvp" "struct componentname *cnp" \ 185"int flags" 186.Ft int 187.Fn VOP_GETPAGES "struct vnode *vp" "voff_t offset" "struct vm_page **m" \ 188"int *count" "int centeridx" "vm_prot_t access_type" "int advice" "int flags" 189.Ft int 190.Fn VOP_PUTPAGES "struct vnode *vp" "voff_t offlo" "voff_t offhi" \ 191"int flags" 192.Ft int 193.Fn VOP_STRATEGY "struct vnode *vp" "struct buf *bp" 194.Ft int 195.Fn VOP_BWRITE "struct buf *bp" 196.Ft int 197.Fn VOP_GETEXTATTR "struct vnode *vp" "int attrnamespace" "const char *name" \ 198"struct uio *uio" "size_t *size" "kauth_cred_t cred" 199.Ft int 200.Fn VOP_SETEXTATTR "struct vnode *vp" "int attrnamespace" "const char *name" \ 201"struct uio *uio" "kauth_cred_t cred" 202.Ft int 203.Fn VOP_LISTEXTATTR "struct vnode *vp" "int attrnamespace" "struct uio *uio" \ 204"size_t *size" "kauth_cred_t cred" 205.Ft int 206.Fn VOP_DELETEEXTATTR "struct vnode *vp" "int attrnamespace" \ 207"const char *name" "kauth_cred_t cred" 208.Pp 209Not all header files are required for each function. 210.Sh DESCRIPTION 211The vnode operations vector describes what operations can be done to 212the file associated with the vnode. 213The system maintains one vnode operations vector for each file system 214type configured into the kernel. 215The vnode operations vector contains a pointer to a function for each 216operation supported by the file system. 217Many of the functions described in the vnode operations vector are 218closely related to their corresponding system calls. 219In most cases, they are called as a result of the system call 220associated with the operation being invoked. 221.Pp 222Functions in the vnode operations vector are invoked using specialized 223macros. 224The following table gives a summary of the operations. 225.Pp 226.Bl -column "VOP_DELETEEXTATTR" "Wake up process sleeping on lock" -compact 227.It Sy Macro Ta Sy Description 228.It VOP_LOOKUP Lookup file name in name cache 229.It VOP_CREATE Create a new file 230.It VOP_MKNOD Make a new device 231.It VOP_OPEN Open a file 232.It VOP_CLOSE Close a file 233.It VOP_ACCESS Determine file accessibility 234.It VOP_GETATTR Get file attributes 235.It VOP_SETATTR Set file attributes 236.It VOP_READ Read from a file 237.It VOP_WRITE Write to a file 238.It VOP_IOCTL Perform device-specific I/O 239.It VOP_FCNTL Perform file control 240.It VOP_POLL Test if poll event has occurred 241.It VOP_KQFILTER Register a knote 242.It VOP_REVOKE Eliminate vode activity 243.It VOP_MMAP Map file into user address space 244.It VOP_FSYNC Flush pending data to disk 245.It VOP_SEEK Test if file is seekable 246.It VOP_REMOVE Remove a file 247.It VOP_LINK Link a file 248.It VOP_RENAME Rename a file 249.It VOP_MKDIR Make a new directory 250.It VOP_RMDIR Remove a directory 251.It VOP_SYMLINK Create a symbolic link 252.It VOP_READDIR Read directory entry 253.It VOP_READLINK Read contents of a symlink 254.It VOP_ABORTOP Abort pending operation 255.It VOP_INACTIVE Release the inactive vnode 256.It VOP_RECLAIM Reclaim vnode for another file 257.It VOP_LOCK Sleep until vnode lock is free 258.It VOP_UNLOCK Wake up process sleeping on lock 259.It VOP_ISLOCKED Test if vnode is locked 260.It VOP_BMAP Logical block number conversion 261.It VOP_PRINT Print debugging information 262.It VOP_PATHCONF Return POSIX pathconf data 263.It VOP_ADVLOCK Advisory record locking 264.It VOP_WHITEOUT Whiteout vnode 265.It VOP_GETPAGES Read VM pages from file 266.It VOP_PUTPAGES Write VM pages to file 267.It VOP_STRATEGY Read/write a file system buffer 268.It VOP_BWRITE Write a file system buffer 269.It VOP_GETEXTATTR Get extended attribute 270.It VOP_SETEXTATTR Set extended attribute 271.It VOP_LISTEXTATTR List extended attributes 272.It VOP_DELETEEXTATTR Remove extended attribute 273.El 274.Pp 275The implementation details of the vnode operations vector are not 276quite what is described here. 277.Pp 278If the file system type does not support a specific operation, it must 279nevertheless assign an appropriate stub in the vnode operations 280vector to do the minimum required of it. 281In most cases, such functions either do nothing or return an error 282value to the effect that it is not supported. 283.Pp 284Many of the functions in the vnode operations vector take a 285componentname structure. 286It is used to encapsulate many parameters into a single function 287argument. 288It has the following structure: 289.Bd -literal 290struct componentname { 291 /* 292 * Arguments to lookup. 293 */ 294 uint32_t cn_nameiop; /* namei operation */ 295 uint32_t cn_flags; /* flags to namei */ 296 kauth_cred_t cn_cred; /* credentials */ 297 /* 298 * Shared between lookup and commit routines. 299 */ 300 char *cn_pnbuf; /* pathname buffer */ 301 const char *cn_nameptr; /* pointer to looked up name */ 302 size_t cn_namelen; /* length of looked up component */ 303 u_long cn_hash; /* hash value of looked up name */ 304 size_t cn_consume; /* chars to consume in lookup() */ 305}; 306.Ed 307.Pp 308The top half of the structure is used exclusively for the pathname 309lookups using 310.Fn VOP_LOOKUP 311and is initialized by the caller. 312The semantics of the lookup are affected by the lookup operation 313specified in 314.Em cn_nameiop 315and the flags specified in 316.Em cn_flags . 317Valid operations are: 318.Pp 319.Bl -tag -offset indent -width LOOKUP -compact 320.It LOOKUP 321perform name lookup only 322.It CREATE 323set up for file creation 324.It DELETE 325set up for file deletion 326.It RENAME 327set up for file renaming 328.It OPMASK 329mask for operation 330.El 331.Pp 332Valid values for 333.Em cn-\*[Gt]cn_flags 334are: 335.Pp 336.Bl -tag -offset indent -width LOCKPARENT -compact 337.It LOCKLEAF 338lock inode on return 339.It LOCKPARENT 340want parent vnode returned locked 341.It NOCACHE 342name must not be left in name cache (see 343.Xr namecache 9 ) 344.It FOLLOW 345follow symbolic links 346.It NOFOLLOW 347do not follow symbolic links (pseudo) 348.It MODMASK 349mask of operational modifiers 350.El 351.Pp 352No vnode operations may be called from interrupt context. 353Most operations also require the vnode to be locked on entry. 354To prevent deadlocks, when acquiring locks on multiple vnodes, the 355lock of parent directory must be acquired before the lock on the child 356directory. 357.Pp 358Vnode operations for a file system type generally should not be 359called directly from the kernel, but accessed indirectly through the 360high-level convenience functions discussed in 361.Xr vnsubr 9 . 362.Sh FUNCTIONS 363.Bl -tag -width compact 364.It Fn VOP_LOOKUP "dvp" "vpp" "cnp" 365Lookup a single pathname component in a given directory. 366The argument 367.Fa dvp 368is the locked vnode of the directory to search and 369.Fa cnp 370is the pathname component to be searched for. 371If the pathname component is found, the address of the resulting 372locked vnode is returned in 373.Fa vpp . 374The operation specified in 375.Em cnp-\*[Gt]cn_nameiop 376indicates 377.Fn VOP_LOOKUP 378the reason for requesting the lookup and uses it to cache 379file system type specific information in the vnode for subsequent 380operations. 381.Pp 382There are three types of lookups: ".", ".." (ISDOTDOT), and regular. 383If the pathname component being searched for is ".", then 384.Fa dvp 385has an extra reference added to it and it is returned in 386.Fa *vpp . 387If the pathname component being search for is ".." (ISDOTDOT), 388.Fa dvp 389is unlocked, the ".." node is locked and then 390.Fa dvp 391is relocked. 392This process preserves the protocol of always locking nodes from root 393downward and prevents deadlock. 394For other pathname components, 395.Fn VOP_LOOKUP 396checks the accessibility of the directory and searches the name cache 397for the pathname component. 398See 399.Xr namecache 9 . 400If the pathname is not found in the name cache, the directory is 401searched for the pathname. 402The resulting locked vnode is returned in 403.Fa vpp . 404.Fa dvp 405is always returned locked. 406.Pp 407On failure 408.Fa *vpp 409is 410.Dv NULL , 411and 412.Fa *dvp 413is left locked. 414If the operation is successful 415.Fa *vpp 416is locked and zero is returned. 417Typically, if 418.Fa *vpp 419and 420.Fa dvp 421are the same vnode the caller will need to release twice (decrement 422the reference count) and unlock once. 423.It Fn VOP_CREATE "dvp" "vpp" "cnp" "vap" 424Create a new file in a given directory. 425The argument 426.Fa dvp 427is the locked vnode of the directory to create the new file in and 428.Fa cnp 429is the pathname component of the new file. 430The argument 431.Fa vap 432specifies the attributes that the new file should be created with. 433If the file is successfully created, the address of the resulting 434locked vnode is returned in 435.Fa vpp 436and zero is returned. 437Regardless of the return value, the directory vnode 438.Fa dvp 439will be unlocked on return. 440.Pp 441This function is called after 442.Fn VOP_LOOKUP 443when a file is being created. 444Normally, 445.Fn VOP_LOOKUP 446will have set the SAVENAME flag in 447.Em cnp-\*[Gt]cn_flags 448to keep the memory pointed to by 449.Em cnp-\*[Gt]cn_pnbuf 450valid. 451If an error is detected when creating the file, this memory is 452released. 453If the file is created successfully it will be released unless the 454SAVESTART flags in specified in 455.Em cnp-\*[Gt]cn_flags . 456.It Fn VOP_MKNOD "dvp" "vpp" "cnp" "vap" 457Make a new device-special file in a given directory. 458The argument 459.Fa dvp 460is the locked vnode of the directory to create the new device-special 461file in and 462.Fa cnp 463is the pathname component of the new device-special file. 464The argument 465.Fa vap 466specifies the attributes that the new device-special file should be 467created with. 468If the file is successfully created, the address of the resulting 469locked vnode is returned in 470.Fa vpp 471and zero is returned. 472.Pp 473This function is called after 474.Fn VOP_LOOKUP 475when a device-special file is being created. 476Normally, 477.Fn VOP_LOOKUP 478will have set the SAVENAME flag in 479.Em cnp-\*[Gt]cn_flags 480to keep the memory pointed to by 481.Em cnp-\*[Gt]cn_pnbuf 482valid. 483If an error is detected when creating the device-special file, 484this memory is released. 485If the device-special file is created successfully it will be released 486unless the SAVESTART flags in specified in 487.Em cnp-\*[Gt]cn_flags . 488.It Fn VOP_OPEN "vp" "mode" "cred" 489Open a file. 490The argument 491.Fa vp 492is the vnode of the file to open and 493.Fa mode 494specifies the access mode required by the calling process. 495The calling credentials are specified by 496.Fa cred . 497The access mode is a set of flags, including FREAD, FWRITE, 498O_NONBLOCK, O_APPEND, etc. 499.Fn VOP_OPEN 500must be called before a file can be accessed by a thread. 501The vnode reference count is incremented. 502.Pp 503.Fn VOP_OPEN 504expects the vnode 505.Fa vp 506to be locked on entry and will leave it locked on return. 507If the operation is successful zero is returned, otherwise an 508appropriate error code is returned. 509.It Fn VOP_CLOSE "vp" "fflag" "cred" 510Close a file. 511The argument 512.Fa vp 513is the vnode of the file to close and 514.Fa fflag 515specifies the access mode by the calling process. 516The possible flags are 517.Dv FREAD , 518.Dv FWRITE 519and 520.Dv FNONBLOCK . 521The calling credentials are specified by 522.Fa cred . 523.Fn VOP_CLOSE 524frees resources allocated by 525.Fn VOP_OPEN . 526.Pp 527The vnode 528.Fa vp 529will be locked on entry and should remain locked on return. 530.It Fn VOP_ACCESS "vp" "mode" "cred" 531Determine the accessibility (permissions) of the file against the 532specified credentials. 533The argument 534.Fa vp 535is the vnode of the file to check, 536.Fa mode 537is the type of access required and 538.Fa cred 539contains the user credentials to check. 540The argument 541.Fa mode 542is a mask which can contain VREAD, VWRITE or VEXEC. 543If the file is accessible in the specified way, zero is returned, 544otherwise an appropriate error code is returned. 545.Pp 546The vnode 547.Fa vp 548will be locked on entry and should remain locked on return. 549.It Fn VOP_GETATTR "vp" "vap" "cred" 550Get specific vnode attributes on a file. 551The argument 552.Fa vp 553is the vnode of the file to get the attributes for. 554The argument 555.Fa cred 556specifies the calling credentials. 557.Fn VOP_GETATTR 558uses the file system type specific data object 559.Em vp-\*[Gt]v_data 560to reference the underlying file attributes. 561Attributes associated with the file are collected by setting the 562required attribute bits in 563.Em vap-\*[Gt]va_mask . 564The attributes are returned in 565.Fa vap . 566Attributes which are not available are set to the value VNOVAL. 567.Pp 568For more information on vnode attributes see 569.Xr vattr 9 . 570.It Fn VOP_SETATTR "vp" "vap" "cred" 571Set specific vnode attributes on a file. 572The argument 573.Fa vp 574is the locked vnode of the file to set the attributes for. 575The argument 576.Fa cred 577specifies the calling credentials. 578.Fn VOP_SETATTR 579uses the file system type specific data object 580.Em vp-\*[Gt]v_data 581to reference the underlying file attributes. 582The new attributes are defined in 583.Fa vap . 584Attributes associated with the file are set by setting the required 585attribute bits in 586.Em vap-\*[Gt]va_mask . 587Attributes which are not being modified by 588.Fn VOP_SETATTR 589should be set to the value VNOVAL. 590If the operation is successful zero is returned, otherwise an 591appropriate error is returned. 592.Pp 593For more information on vnode attributes see 594.Xr vattr 9 . 595.It Fn VOP_READ "vp" "uio" "ioflag" "cred" 596Read the contents of a file. 597The argument 598.Fa vp 599is the vnode of the file to read from, 600.Fa uio 601is the location to read the data into, 602.Fa ioflag 603is a set of flags and 604.Fa cred 605are the credentials of the calling process. 606.Pp 607The 608.Fa ioflag 609argument is used to give directives and hints to the file system. 610When attempting a read, the high 16 bits are used to provide a 611read-ahead hint (in unit of file system blocks) that the file system 612should attempt. 613The low 16 bits are a bit mask which can contain the following flags: 614.Pp 615.Bl -tag -offset indent -width IO_ALTSEMANTICS -compact 616.It IO_UNIT 617do I/O as atomic unit 618.It IO_APPEND 619append write to end 620.It IO_SYNC 621sync I/O file integrity completion 622.It IO_NODELOCKED 623underlying node already locked 624.It IO_NDELAY 625FNDELAY flag set in file table 626.It IO_DSYNC 627sync I/O data integrity completion 628.It IO_ALTSEMANTICS 629use alternate I/O semantics 630.It IO_NORMAL 631operate on regular data 632.It IO_EXT 633operate on extended attributes 634.It IO_DIRECT 635do not buffer data in the kernel 636.El 637.Pp 638Zero is returned on success, otherwise an error is returned. 639The vnode should be locked on entry and remains locked on exit. 640.It Fn VOP_WRITE "vp" "uio" "ioflag" "cred" 641Write to a file. 642The argument 643.Fa vp 644is the vnode of the file to write to, 645.Fa uio 646is the location of the data to write, 647.Fa ioflag 648is a set of flags and 649.Fa cred 650are the credentials of the calling process. 651.Pp 652The 653.Fa ioflag 654argument is used to give directives and hints to the file system. 655The low 16 bits are a bit mask which can contain the same flags as 656.Fn VOP_READ . 657.Pp 658Zero is returned on success, otherwise an error is returned. 659The vnode should be locked on entry and remains locked on exit. 660.It Fn VOP_IOCTL "vp" "command" "data" "fflag" "cred" 661Perform device-specific I/O. 662The argument 663.Fa vp 664is the locked vnode of the file, normally representing a device. 665The argument 666.Fa command 667specifies the device-specific operation to perform and 668.Fa cnp 669provides extra data for the specified operation. 670The argument 671.Fa fflags 672is a set of flags. 673The argument 674.Fa cred 675is the caller's credentials. 676If the operation is successful, zero is 677returned, otherwise an appropriate error code is returned. 678.Pp 679Most file systems do not supply a function for 680.Fn VOP_IOCTL . 681This function implements the 682.Xr ioctl 2 683system call. 684.It Fn VOP_FCNTL "vp" "command" "data" "fflag" "cred" 685Perform file control. 686The argument 687.Fa vp 688is the locked vnode of the file. 689The argument 690.Fa command 691specifies the operation to perform and 692.Fa cnp 693provides extra data for the specified operation. 694The argument 695.Fa fflags 696is a set of flags. 697The argument 698.Fa cred 699is the caller's credentials. 700If the operation is successful, zero is returned, otherwise an 701appropriate error code is returned. 702.It Fn VOP_POLL "vp" "events" 703Test if a poll event has occurred. 704The argument 705.Fa vp 706is the vnode of the file to poll. 707It returns any events of interest as specified by 708.Fa events 709that may have occurred for the file. 710The argument 711.Fa events 712is a set of flags as specified by 713.Xr poll 2 . 714.It Fn VOP_KQFILTER "vp" "kn" 715Register a knote 716.Fa kn 717with the vnode 718.Fa vn . 719If the operation is successful zero is returned, otherwise an 720appropriate error code is returned. 721.It Fn VOP_REVOKE "vp" "flags" 722Eliminate all activity associated with the vnode 723.Fa vp . 724The argument 725.Fa flags 726is a set of flags. 727If REVOKEALL is set in 728.Fa flags 729all vnodes aliased to the vnode 730.Fa vp 731are also eliminated. 732If the operation is successful zero is returned, otherwise an 733appropriate error is returned. 734.It Fn VOP_MMAP "vp" "prot" "cred" 735Inform file system that 736.Fa vp 737is in the process of being memory mapped. 738The argument 739.Fa prot 740specifies the vm access protection the vnode is going to be mapped with. 741The argument 742.Fa cred 743is the caller's credentials. 744If the file system allows the memory mapping, zero is returned, otherwise 745an appropriate error code is returned. 746.Pp 747Most file systems do not supply a function for 748.Fn VOP_MMAP 749and use 750.Fn genfs_mmap 751to default for success. 752Only file systems which do not integrate with the page cache at all 753typically want to disallow memory mapping. 754.It Fn VOP_FSYNC "vp" "cred" "flags" "offlo" "offhi" 755Flush pending data buffers for a file to disk. 756The argument 757.Fa vp 758is the locked vnode of the file for flush. 759The argument 760.Fa cred 761is the caller's credentials. 762The argument 763.Fa flags 764is a set of flags. 765If FSYNC_WAIT is specified in 766.Fa flags , 767the function should wait for I/O to complete before returning. 768The argument 769.Fa offlo 770and 771.Fa offhi 772specify the range of file to flush. 773If the operation is successful zero is returned, otherwise an 774appropriate error code is returned. 775.Pp 776This function implements the 777.Xr sync 2 778and 779.Xr fsync 2 780system calls. 781.It Fn VOP_SEEK "vp" "oldoff" "newoff" "cred" 782Test if the file is seekable for the specified offset 783.Fa newoff . 784The argument 785.Fa vp 786is the locked vnode of the file to test. 787For most file systems this function simply tests if 788.Fa newoff 789is valid. 790If the specified 791.Fa newoff 792is less than zero, the function returns error code EINVAL. 793.It Fn VOP_REMOVE "dvp" "vp" "cnp" 794Remove a file. 795The argument 796.Fa dvp 797is the locked vnode of the directory to remove the file from and 798.Fa vp 799is the locked vnode of the file to remove. 800The argument 801.Fa cnp 802is the pathname component about the file to remove. 803If the operation is successful zero is returned, otherwise an 804appropriate error code is returned. 805Both 806.Fa dvp 807and 808.Fa vp 809are locked on entry and are to be unlocked before returning. 810.It Fn VOP_LINK "dvp" "vp" "cnp" 811Link to a file. 812The argument 813.Fa dvp 814is the locked node of the directory to create the new link and 815.Fa vp 816is the vnode of the file to be linked. 817The argument 818.Fa cnp 819is the pathname component of the new link. 820If the operation is successful zero is returned, otherwise an error 821code is returned. 822The directory vnode 823.Fa dvp 824should be locked on entry and will be released and unlocked on return. 825The vnode 826.Fa vp 827should not be locked on entry and will remain unlocked on return. 828.It Fn VOP_RENAME "fdvp" "fvp" "fcnp" "tdvp" "tvp" "tcnp" 829Rename a file. 830The argument 831.Fa fdvp 832is the vnode of the old parent directory containing in the file to be 833renamed and 834.Fa fvp 835is the vnode of the file to be renamed. 836The argument 837.Fa fcnp 838is the pathname component about the file to be renamed. 839The argument 840.Fa tdvp 841is the vnode of the new directory of the target file and 842.Fa tvp 843is the vnode of the target file (if it exists). 844The argument 845.Fa tcnp 846is the pathname component about the file's new name. 847If the operation is successful zero is returned, otherwise and error 848code is returned. 849.Pp 850The source directory and file vnodes should be unlocked and their 851reference counts should be incremented before entry. 852The target directory and file vnodes should both be locked on entry. 853.Fn VOP_RENAME 854updates the reference counts prior to returning. 855.It Fn VOP_MKDIR "dvp" "vpp" "cnp" "vap" 856Make a new directory in a given directory. 857The argument 858.Fa dvp 859is the locked vnode of the directory to create the new directory in and 860.Fa cnp 861is the pathname component of the new directory. 862The argument 863.Fa vap 864specifies the attributes that the new directory should be created 865with. 866If the file is successfully created, the address of the resulting 867locked vnode is returned in 868.Fa vpp 869and zero is returned. 870.Pp 871This function is called after 872.Fn VOP_LOOKUP 873when a directory is being created. 874Normally, 875.Fn VOP_LOOKUP 876will have set the SAVENAME flag in 877.Em cnp-\*[Gt]cn_flags 878to keep the memory pointed to by 879.Em cnp-\*[Gt]cn_pnbuf 880valid. 881If an error is detected when creating the directory, this memory is 882released. 883If the directory is created successfully it will be released unless 884the SAVESTART flags in specified in 885.Em cnp-\*[Gt]cn_flags . 886.It Fn VOP_RMDIR "dvp" "vp" "cnp" 887Remove a directory in a given directory. 888The argument 889.Fa dvp 890is the locked vnode of the directory to remove the directory from and 891.Fa vp 892is the locked vnode of the directory to remove. 893The argument 894.Fa cnp 895is the pathname component of the directory. 896Zero is returned on success, otherwise an error code is returned. 897Both 898.Fa dvp 899and 900.Fa vp 901should be locked on entry and will be released and unlocked on return. 902.It Fn VOP_SYMLINK "dvp" "vpp" "cnp" "vap" "target" 903Create a symbolic link in a given directory. 904The argument 905.Fa dvp 906is the locked vnode of the directory to create the symbolic link in 907and 908.Fa cnp 909is the pathname component of the symbolic link. 910The argument 911.Fa vap 912specifies the attributes that the symbolic link should be created 913with and 914.Fa target 915specifies the pathname of the target of the symbolic link. 916If the symbolic link is successfully created, the address of the 917resulting locked vnode is returned in 918.Fa vpp 919and zero is returned. 920.Pp 921This function is called after 922.Fn VOP_LOOKUP 923when a symbolic link is being created. 924Normally, 925.Fn VOP_LOOKUP 926will have set the SAVENAME flag in 927.Em cnp-\*[Gt]cn_flags 928to keep the memory pointed to by 929.Em cnp-\*[Gt]cn_pnbuf 930valid. 931If an error is detected when creating the symbolic link, this memory 932is released. 933If the symbolic link is created successfully it will be released 934unless the SAVESTART flags in specified in 935.Em cnp-\*[Gt]cn_flags . 936.It Fn VOP_READDIR "vp" "uio" "cred" "eofflag" "cookies" "ncookies" 937Read directory entry. 938The argument 939.Fa vp 940is the vnode of the directory to read the contents of and 941.Fa uio 942is the destination location to read the contents into. 943The argument 944.Fa cred 945is the caller's credentials. 946The argument 947.Fa eofflag 948is the pointer to a flag which is set by 949.Fn VOP_READDIR 950to indicate an end-of-file condition. 951If 952.Fa eofflag 953is 954.Dv NULL , 955the end-of-file condition is not returned. 956The arguments 957.Fa cookies 958and 959.Fa ncookies 960specify the addresses for the list and number of directory seek 961cookies generated for NFS. 962Both 963.Fa cookies 964and 965.Fa ncookies 966should be 967.Dv NULL 968if they aren't required to be returned by 969.Fn VOP_READDIR . 970The directory contents are read into struct dirent structures and 971.Fa uio-\*[Gt]uio_offset 972is set to the offset of the next unread directory entry. 973This offset may be used in a following invocation to continue a 974sequential read of the directory contents. 975If the operation is successful zero is returned, otherwise an 976appropriate error code is returned. 977.Pp 978The directory should be locked on entry and will remain locked on 979return. 980.Pp 981In case 982.Fa ncookies 983and 984.Fa cookies 985are supplied, one cookie should be returned per directory entry. 986The value of the cookie for each directory entry should be the offset 987within the directory where the on-disk version of the following 988directory entry starts. 989That is, for each directory entry 990.Fa i , 991the corresponding cookie should refer to the offset of directory entry 992.Fa i + 1 . 993.Pp 994Note that the 995.Fa cookies 996array must be allocated by the callee using the M_TEMP malloc type as 997callers of 998.Fn VOP_READDIR 999must be able to free the allocation. 1000.It Fn VOP_READLINK "vp" "uio" "cred" 1001Read the contents of a symbolic link. 1002The argument 1003.Fa vp 1004is the locked vnode of the symlink and 1005.Fa uio 1006is the destination location to read the contents into. 1007The argument 1008.Fa cred 1009is the credentials of the caller. 1010If the operation is successful zero is returned, otherwise an error 1011code is returned. 1012.Pp 1013The vnode should be locked on entry and will remain locked on return. 1014.It Fn VOP_ABORTOP "dvp" "cnp" 1015Abort pending operation on vnode 1016.Fa dvp 1017and free resources allocated in 1018.Fa cnp . 1019.Pp 1020This operation is rarely implemented in file systems and 1021.Fn genfs_abortop 1022is typically used instead. 1023.It Fn VOP_INACTIVE "vp" 1024Release the inactive vnode. 1025.Fn VOP_INACTIVE 1026is called when the kernel is no longer using the vnode. 1027This may be because the reference count reaches zero or it may be that 1028the file system is being forcibly unmounted while there are open 1029files. 1030It can be used to reclaim space for open but deleted files. 1031The argument 1032.Fa vp 1033is the locked vnode to be released. 1034If the operation is successful zero is returned, otherwise an 1035appropriate error code is returned. 1036The vnode 1037.Fa vp 1038must be locked on entry, and will be unlocked on return. 1039.It Fn VOP_RECLAIM "vp" 1040Reclaim the vnode for another file system. 1041.Fn VOP_RECLAIM 1042is called when a vnode is being reused for a different file system. 1043Any file system specific resources associated with the vnode should be 1044freed. 1045The argument 1046.Fa vp 1047is the vnode to be reclaimed. 1048If the operation is successful zero is returned, otherwise an 1049appropriate error code is returned. 1050The vnode 1051.Fa vp 1052should not be locked on entry, and will remain unlocked on return. 1053.It Fn VOP_LOCK "vp" "flags" 1054Sleep until vnode lock is free. 1055The argument 1056.Fa vp 1057is the vnode of the file to be locked. 1058The argument 1059.Fa flags 1060is 1061.Dv LK_EXCLUSIVE 1062to take the lock exclusively or 1063.Dv LK_SHARED 1064to take a shared lock. 1065If 1066.Fa flags 1067contains 1068.Dv LK_NOWAIT 1069and the lock is busy, the operation will return immediately with an error code. 1070If the operation is successful zero is returned, otherwise an 1071appropriate error code is returned. 1072.Fn VOP_LOCK 1073is used to serialize access to the file system such as to prevent two 1074writes to the same file from happening at the same time. 1075Kernel code should use 1076.Xr vn_lock 9 1077to lock a vnode rather than calling 1078.Fn VOP_LOCK 1079directly. 1080.It Fn VOP_UNLOCK "vp" 1081Wake up process sleeping on lock. 1082The argument 1083.Fa vp 1084is the vnode of the file to be unlocked. 1085If the operation is successful zero is returned, otherwise an 1086appropriate error code is returned. 1087.Fn VOP_UNLOCK 1088is used to serialize access to the file system such as to prevent two 1089writes to the same file from happening at the same time. 1090.It Fn VOP_ISLOCKED "vp" 1091Test if the vnode 1092.Fa vp 1093is locked. 1094Possible return values are 1095.Dv LK_EXCLUSIVE , 1096.Dv LK_SHARED 1097or 0 for lock held exclusively by the calling thread, shared lock held 1098by anyone or unlocked, respectively. 1099.Pp 1100This function must never be used to make locking decisions at run time: 1101it is provided only for diagnostic purposes. 1102.It Fn VOP_BMAP "vp" "bn" "vpp" "bnp" "runp" 1103Convert the logical block number 1104.Fa bn 1105of a file specified by vnode 1106.Fa vp 1107to its physical block number on the disk. 1108The physical block is returned in 1109.Fa bnp . 1110In case the logical block is not allocated, \-1 is used. 1111.Pp 1112If 1113.Fa vpp 1114is not 1115.Dv NULL , 1116the vnode of the device vnode for the file system is 1117returned in the address specified by 1118.Fa vpp . 1119If 1120.Fa runp 1121is not 1122.Dv NULL , 1123the number of contiguous blocks starting from the next block after 1124the queried block will be returned in 1125.Fa runp . 1126.It Fn VOP_PRINT "vp" 1127Print debugging information. 1128The argument 1129.Fa vp 1130is the vnode to print. 1131If the operation is successful zero is returned, otherwise an 1132appropriate error code is returned. 1133.It Fn VOP_PATHCONF "vp" "name" "retval" 1134Implement POSIX 1135.Xr pathconf 2 1136and 1137.Xr fpathconf 2 1138support. 1139The argument 1140.Fa vp 1141is the locked vnode to get information about. 1142The argument 1143.Fa name 1144specified the type of information to return. 1145The information is returned in the address specified by 1146.Fa retval . 1147Valid values for 1148.Fa name 1149are: 1150.Pp 1151.Bl -tag -offset indent -width _PC_CHOWN_RESTRICTED -compact 1152.It _PC_LINK_MAX 1153return the maximum number of links to a file 1154.It _PC_NAME_MAX 1155return the maximum number of bytes in a file name 1156.It _PC_PATH_MAX 1157return the maximum number of bytes in a pathname 1158.It _PC_PIPE_BUF 1159return the maximum number of bytes which will be written atomically to 1160a pipe 1161.It _PC_CHOWN_RESTRICTED 1162return 1 if appropriate privileges are required for the 1163.Xr chown 2 1164system call, otherwise zero 1165.It _PC_NO_TRUNC 1166return if file names longer than KERN_NAME_MAX are truncated 1167.El 1168.Pp 1169If 1170.Fa name 1171is recognized, 1172.Fa *retval 1173is set to the specified value and zero is returned, otherwise an 1174appropriate error is returned. 1175.It Fn VOP_ADVLOCK "vp" "id" "op" "fl" "flags" 1176Manipulate Advisory record locks on a vnode. 1177The argument 1178.Fa vp 1179is the vnode on which locks are manipulated. 1180The argument 1181.Fa id 1182is the id token which is changing the lock and 1183.Fa op 1184is the 1185.Xr fcntl 2 1186operation to perform. 1187Valid values are: 1188.Pp 1189.Bl -tag -offset indent -width F_UNLCK -compact 1190.It F_SETLK 1191set lock 1192.It F_GETLK 1193get the first conflicted lock 1194.It F_UNLCK 1195clear lock 1196.El 1197.Pp 1198The argument 1199.Fa fl 1200is a description of the lock. 1201In the case of 1202.Dv SEEK_CUR , 1203The caller should add the current file offset to 1204fl-\*[Gt]l_start beforehand. 1205.Fn VOP_ADVLOCK 1206treats 1207.Dv SEEK_CUR 1208as 1209.Dv SEEK_SET . 1210.Pp 1211The argument 1212.Fa flags 1213is the set of flags. 1214Valid values are: 1215.Pp 1216.Bl -tag -offset indent -width F_FLOCK -compact 1217.It F_WAIT 1218wait until lock is granted 1219.It F_FLOCK 1220use 1221.Xr flock 2 1222semantics for lock 1223.It F_POSIX 1224use POSIX semantics for lock 1225.El 1226.Pp 1227If the operation is successful zero is returned, otherwise an 1228appropriate error is returned. 1229.It Fn VOP_WHITEOUT "dvp" "cnp" "flags" 1230Whiteout pathname component in directory with vnode 1231.Fa dvp . 1232The argument 1233.Fa cnp 1234specifies the pathname component to whiteout. 1235.It Fn VOP_GETPAGES "vp" "offset" "m" "count" "centeridx" "access_type" "advice" "flags" 1236Read VM pages from file. 1237The argument 1238.Fa vp 1239is the locked vnode to read the VM pages from. 1240The argument 1241.Fa offset 1242is offset in the file to start accessing and 1243.Fa m 1244is an array of VM pages. 1245The argument 1246.Fa count 1247points a variable that specifies the number of pages to read. 1248If the operation is successful zero is returned, otherwise an 1249appropriate error code is returned. 1250If PGO_LOCKED is specified in 1251.Em flags , 1252.Fn VOP_GETPAGES 1253might return less pages than requested. 1254In that case, the variable pointed to by 1255.Em count 1256will be updated. 1257.Pp 1258This function is primarily used by the page-fault handing mechanism. 1259.It Fn VOP_PUTPAGES "vp" "offlo" "offhi" "flags" 1260Write modified (dirty) VM pages to file. 1261The argument 1262.Fa vp 1263is the vnode to write the VM pages to. 1264The vnode's vm object lock 1265.Va ( v_uobj.vmobjlock ) 1266must be held by the caller and will be released upon return. 1267The arguments 1268.Fa offlo 1269and 1270.Fa offhi 1271specify the range of VM pages to write. 1272In case 1273.Fa offhi 1274is given as 0, all pages at and after the start offset 1275.Fa offlo 1276belonging the vnode 1277.Fa vp 1278will be written. 1279The argument 1280.Fa flags 1281controls the behavior of the routine and takes the vm pager's 1282flags 1283.Dv ( PGO_ -prefixed ) . 1284If the operation is successful zero is returned, otherwise an 1285appropriate error code is returned. 1286.Pp 1287The function is primarily used by the pageout handling mechanism and 1288is commonly implemented indirectly 1289by 1290.Fn genfs_putpages 1291with the help of 1292.Fn VOP_STRATEGY 1293and 1294.Fn VOP_BMAP . 1295.It Fn VOP_STRATEGY "vp" "bp" 1296Read/write a file system buffer. 1297The argument 1298.Fa vp 1299is the vnode to read/write to. 1300The argument 1301.Fa bp 1302is the buffer to be read or written. 1303.Fn VOP_STRATEGY 1304will either read or write data to the file depending on the value of 1305.Em bp-\*[Gt]b_flags . 1306If the operation is successful zero is returned, otherwise an 1307appropriate error code is returned. 1308.It Fn VOP_BWRITE "bp" 1309Write a file system buffer. 1310The argument 1311.Fa bp 1312specifies the buffer to be written. 1313If the operation is successful zero is returned, otherwise an 1314appropriate error code is returned. 1315.It Fn VOP_GETEXTATTR "vp" "attrnamespace" "name" "uio" "size" "cred" 1316Get an extended attribute. 1317The argument 1318.Fa vp 1319is the locked vnode of the file or directory from which to retrieve the 1320attribute. 1321The argument 1322.Fa attrnamespace 1323specifies the extended attribute namespace. 1324The argument 1325.Fa name 1326is a nul-terminated character string naming the attribute to retrieve. 1327The argument 1328.Fa uio , 1329if not 1330.Dv NULL , 1331specifies where the extended attribute value is to be written. 1332The argument 1333.Fa size , 1334if not 1335.Dv NULL , 1336will contain the number of bytes required to read all of 1337the attribute data upon return. 1338In most cases, 1339.Fa uio 1340will be 1341.Dv NULL 1342when 1343.Fa size 1344is not, and vice versa. 1345The argument 1346.Fa cred 1347specifies the user credentials to use when authorizing the request. 1348.It Fn VOP_SETEXTATTR "vp" "attrnamespace" "name" "uio" "cred" 1349Set an extended attribute. 1350The argument 1351.Fa vp 1352is the locked vnode of the file or directory to which to store the 1353attribute. 1354The argument 1355.Fa namespace 1356specifies the extended attribute namespace. 1357The argument 1358.Fa name 1359is a nul-terminated character string naming the attribute to store. 1360The argument 1361.Fa uio 1362specifies the source of the extended attribute data. 1363The argument 1364.Fa cred 1365specifies the user credentials to use when authorizing the request. 1366.It Fn VOP_LISTEXTATTR "vp" "attrnamespace" "uio" "size" "cred" 1367Retrieve the list of extended attributes. 1368The argument 1369.Fa vp 1370is the locked vnode of the file or directory whose attributes are to be listed. 1371The argument 1372.Fa attrnamespace 1373specifies the extended attribute namespace. 1374The argument 1375.Fa uio , 1376if not 1377.Dv NULL , 1378specifies where the extended attribute list is to be written. 1379The argument 1380.Fa size , 1381if not 1382.Dv NULL , 1383will contain the number of bytes required to read all of 1384the attribute names upon return. 1385In most cases, 1386.Fa uio 1387will be 1388.Dv NULL 1389when 1390.Fa size 1391is not, and vice versa. 1392The argument 1393.Fa cred 1394specifies the user credentials to use when authorizing the request. 1395.It Fn VOP_DELETEEXTATTR "vp" "attrnamespace" "name" "cred" 1396Remove attribute 1397.Fa name 1398from file associated with 1399.Fa vp . 1400The argument 1401.Fa attrnamespace 1402specifies the extended attribute namespace. 1403If full removal is not supported, the file system should return 1404.Er EOPNOTSUPP 1405to allow the caller to zero out the value with 1406.Fn VOP_SETEXTATTR . 1407.El 1408.Sh ERRORS 1409.Bl -tag -width Er 1410.It Bq Er EACCES 1411Access for the specified operation is denied. 1412.It Bq Er EDQUOT 1413Quota exceeded. 1414.It Bq Er EINVAL 1415attempt to read from an illegal offset in the directory; unrecognized 1416input 1417.It Bq Er EIO 1418a read error occurred while reading the directory or reading the 1419contents of a symbolic link 1420.It Bq Er EJUSTRETURN 1421A CREATE or RENAME operation would be successful. 1422.It Bq Er ENOATTR 1423The requested attribute is not defined for this vnode. 1424.It Bq Er ENOENT 1425The component was not found in the directory. 1426.It Bq Er ENOSPC 1427The file system is full. 1428.It Bq Er ENOTDIR 1429The vnode does not represent a directory. 1430.It Bq Er ENOTEMPTY 1431attempt to remove a directory which is not empty 1432.It Bq Er EPERM 1433an attempt was made to change an immutable file 1434.It Bq Er EROFS 1435the file system is read-only 1436.El 1437.Sh SEE ALSO 1438.Xr extattr 9 , 1439.Xr intro 9 , 1440.Xr namei 9 , 1441.Xr vattr 9 , 1442.Xr vfs 9 , 1443.Xr vfsops 9 , 1444.Xr vnode 9 1445.Sh HISTORY 1446The vnode operations vector, its functions and the corresponding 1447macros appeared in 1448.Bx 4.3 . 1449