libutil-47.30.1.tar.gz

[apple/libutil.git] / wipefs.3

diff --git a/wipefs.3 b/wipefs.3
index 0f14dfc8a5ffb78d68d3c86418ae345373ee3807..21cee1c4e7b452cac0114d7bc9c78485acfbb8e6 100644 (file)
--- a/wipefs.3
+++ b/wipefs.3
@@ -1,5 +1,5 @@
 .\"\r
-.\" Copyright (c) 2008 Apple Inc. All rights reserved.\r
+.\" Copyright (c) 2008,2011 Apple Inc. All rights reserved.\r
 .\"\r
 .\" @APPLE_LICENSE_HEADER_START@\r
 .\" \r
@@ -20,7 +20,7 @@
 .\" \r
 .\" @APPLE_LICENSE_HEADER_END@\r
 .\"\r
-.Dd 2/25/08               \" DATE \r
+.Dd 6/30/11               \" DATE \r
 .Dt libutil 3      \" Program name and manual section number \r
 .Os Mac OS X\r
 .Sh NAME                 \" Section Header - required - don't modify \r
@@ -38,14 +38,20 @@
 .In wipefs.h\r
 .Ft int\r
 .Fo wipefs_alloc\r
-.Fa "int file_desc"\r
+.Fa "int fd"\r
 .Fa "size_t block_size"\r
-.Fa "wipefs_ctx *handlep"\r
+.Fa "wipefs_ctx *handle"\r
+.Fc\r
+.Ft int\r
+.Fo wipefs_include_blocks\r
+.Fa "wipefs_ctx handle"\r
+.Fa "off_t block_offset"\r
+.Fa "off_t nblocks"\r
 .Fc\r
 .Ft int\r
 .Fo wipefs_except_blocks\r
 .Fa "wipefs_ctx handle"\r
-.Fa "off_t blockoff"\r
+.Fa "off_t block_offset"\r
 .Fa "off_t nblocks"\r
 .Fc\r
 .Ft int\r
@@ -54,10 +60,20 @@
 .Fc\r
 .Ft void\r
 .Fo wipefs_free\r
-.Fa "wipefs_ctx *handlep"\r
+.Fa "wipefs_ctx *handle"\r
 .Fc\r
 .Sh DESCRIPTION          \" Section Header - required - don't modify\r
-The wipefs family of functions wipe existing file systems on a volume.  This is usually used by the newfs_* utilities before they create new file systems on the volume, so that the existing file system will not be mounted accidentally after the new file system is created.\r
+The wipefs family of functions wipe existing file systems on a volume.  A\r
+.Li DKIOCUNMAP\r
+ioctl is sent to the device to invalidate all of its content.\r
+Then zeroes are written to various locations that are used by various file systems to recognize their content and mount their volumes.\r
+This is usually used by the newfs_* utilities before they create new file systems on the volume, so that the existing file system will not be mounted accidentally after the new file system is created.\r
+.Pp\r
+.Sy NOTE:\r
+These routines do not overwrite all volume structures.\r
+These routines do not securely erase the previous content.\r
+They only overwrite enough to make sure that the normal utilities will no longer recognize any file system content.\r
+It is possible that previous file system content could be recovered by other means.\r
 .Pp\r
 The\r
 .Fn wipefs_alloc\r
@@ -78,6 +94,15 @@ must be supplied if
 is a regular file.  This function does not write any data to the volume.\r
 .Pp\r
 The\r
+.Fn wipefs_include_blocks\r
+function tells wipefs to write zeroes in the block range provided, in addition to any other ranges\r
+it would normally write.  This may be more efficient than if the caller were to write this range\r
+separately, especially if the block range overlaps or is contiguous with other ranges that wipefs\r
+will write.  This function does not write any data to the volume.  If this function is called\r
+multiple times, the union of all the ranges provided will be written by\r
+.Fn wipefs_wipe .\r
+.Pp\r
+The\r
 .Fn wipefs_except_blocks\r
 function tells wipefs not to write anything in the block range provided.  This function is used for performance\r
 optimizations if the caller will write to these blocks.  It is the caller's responsibility to write to these blocks.\r
@@ -88,8 +113,10 @@ written by
 .Pp\r
 The\r
 .Fn wipefs_wipe\r
-function writes data to the volume to wipe out existing file systems on it.\r
-.Cm Caution:\r
+function sends a\r
+.Li DKIOCUNMAP\r
+ioctl and then writes data to the volume to wipe out existing file systems on it.\r
+.Sy CAUTION:\r
 this function destroys any file system or partition scheme on the volume represented by\r
 .Fa file_desc .\r
 If\r
@@ -112,6 +139,7 @@ to NULL.
 .Sh RETURN VALUES\r
 The\r
 .Fn wipefs_alloc ,\r
+.Fn wipefs_include_blocks ,\r
 .Fn wipefs_except_blocks\r
 and\r
 .Fn wipefs_wipe\r