1.\" $OpenBSD: vnd.4,v 1.21 2008/03/17 16:30:36 sobrado Exp $ 2.\" $NetBSD: vnd.4,v 1.1 1995/12/30 18:10:48 thorpej Exp $ 3.\" 4.\" Copyright (c) 1995 Jason R. Thorpe. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed for the NetBSD Project 18.\" by Jason R. Thorpe. 19.\" 4. Neither the name of the author nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 24.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 25.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 26.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 27.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 28.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 29.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 30.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 31.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.Dd $Mdocdate: March 17 2008 $ 36.Dt VND 4 37.Os 38.Sh NAME 39.Nm vnd 40.Nd vnode disk driver 41.Sh SYNOPSIS 42.Cd "pseudo-device vnd" Op Ar count 43.Sh DESCRIPTION 44The 45.Nm 46driver provides a disk-like interface to a file. 47This is useful for a variety of applications, including swap files and 48building miniroot or floppy disk images. 49There are two variants, the traditional 50.Nm 51that bypasses the buffer cache and thus is suitable for swap on files, but 52not for building disk-images, and the 53.Nm svnd 54.Po 55.Dq safe 56.Nm 57.Pc 58variant that goes 59through the buffer cache, thereby maintaining cache-coherency after the 60block-device is closed which makes it suitable for creating disk images. 61The latter is not good for swapping on, though. 62.Pp 63This document assumes familiarity with how to generate kernels and 64how to properly configure disks and pseudo-devices in a kernel 65configuration file. 66.Pp 67In order to compile in support for 68.Nm vnd 69devices, a line similar to the following must be present in the kernel 70configuration file: 71.Bd -unfilled -offset indent 72pseudo-device vnd 4 # vnode disk driver 73.Ed 74.Pp 75The 76.Ar count 77argument is how many 78.Nm vnds 79memory is allocated for at boot time. 80In this example, no more than 4 81.Nm vnds 82may be configured. 83.Pp 84There is a run-time utility that is used for configuring 85.Nm vnds . 86See 87.Xr vnconfig 8 88for more information. 89.Sh IOCTL INTERFACE 90The following 91.Xr ioctl 2 92calls are defined in 93.Aq Pa dev/vndioctl.h : 94.Bl -tag -width Ds 95.It Dv VNDIOCSET Fa "struct vnd_ioctl *" 96Associate the file 97.Va vnd_file 98with a 99.Nm 100pseudo device, optionally encrypted using the Blowfish cipher and the key 101specified in 102.Va vnd_key 103of length 104.Va vnd_keylen . 105Encryption only works with 106.Nm svnd 107devices. 108The size of the configured device is returned in 109.Va vnd_size . 110.Bd -literal -offset indent 111struct vnd_ioctl { 112 char *vnd_file; 113 off_t vnd_size; 114 u_char *vnd_key; 115 int vnd_keylen; 116}; 117.Ed 118.It Dv VNDIOCCLR Fa "struct vnd_ioctl *" 119Disassociate a 120.Nm 121device. 122.It Dv VNDIOCGET Fa "struct vnd_user *" 123Get the associated file name, device, inode number, and unit number of a 124.Nm 125device. 126If 127.Va vnu_unit 128is \-1, information on the 129.Nm 130device corresponding to the file descriptor passed to 131.Xr ioctl 2 132will be returned. 133Otherwise, 134.Va vnu_unit 135may contain the unit number of another 136.Nm 137device. 138This allows for opening just 139.Li vnd0 140and querying all available devices. 141.Bd -literal -offset indent 142struct vnd_user { 143 char vnufile[VNDNLEN]; 144 int vnu_unit; 145 dev_t vnu_dev; 146 ino_t vnu_ino; 147}; 148.Ed 149.El 150.Pp 151Additionally, some 152.Xr disklabel 8 153related 154.Xr ioctl 2 155calls defined in 156.Aq Pa sys/disklabel.h 157are available: 158.Dv DIOCGDINFO , 159.Dv DIOCSDINFO , 160.Dv DIOCWDINFO , 161and 162.Dv DIOCWLABEL . 163They are documented in 164.Xr sd 4 . 165.Sh FILES 166.Bl -tag -width /dev/{,r}{,s}vnd* -compact 167.It Pa /dev/{,r}{,s}vnd* 168.Nm 169device special files 170.El 171.Sh SEE ALSO 172.Xr ioctl 2 , 173.Xr sd 4 , 174.Xr disklabel 5 , 175.Xr MAKEDEV 8 , 176.Xr config 8 , 177.Xr disklabel 8 , 178.Xr fdisk 8 , 179.Xr fsck 8 , 180.Xr mount 8 , 181.Xr newfs 8 , 182.Xr vnconfig 8 183.Sh HISTORY 184The 185.Nm 186disk driver was originally written at the University of 187Utah. 188The 189.Nm svnd 190variant was first seen in 191.Ox 2.1 . 192.Sh BUGS 193The 194.Nm 195driver does not work if the file does not reside in a local filesystem. 196However the 197.Nm svnd 198variant does. 199