wipefs.3

   1 .\"
   2 .\" Copyright (c) 2008 Apple Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. Please obtain a copy of the License at
  10 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  11 .\" file.
  12 .\"
  13 .\" The Original Code and all software distributed under the License are
  14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18 .\" Please see the License for the specific language governing rights and
  19 .\" limitations under the License.
  20 .\"
  21 .\" @APPLE_LICENSE_HEADER_END@
  22 .\"
  23 .Dd 2/25/08               \" DATE
  24 .Dt libutil 3      \" Program name and manual section number
  25 .Os Mac OS X
  26 .Sh NAME                 \" Section Header - required - don't modify
  27 .\" The following lines are read in generating the apropos(man -k) database. Use only key
  28 .\" words here as the database is built based on the words here and in the .ND line.
  29 .Nm wipefs_alloc ,
  30 .Nm wipefs_except_blocks ,
  31 .Nm wipefs_wipe ,
  32 .Nm wipefs_free
  33 .\" Use .Nm macro to designate other names for the documented program.
  34 .Nd wipes existing file systems on a volume
  35 .Sh LIBRARY             \" Section Header - required - don't modify
  36 .Lb libutil
  37 .Sh SYNOPSIS
  38 .In wipefs.h
  39 .Ft int
  40 .Fo wipefs_alloc
  41 .Fa "int file_desc"
  42 .Fa "size_t block_size"
  43 .Fa "wipefs_ctx *handlep"
  44 .Fc
  45 .Ft int
  46 .Fo wipefs_except_blocks
  47 .Fa "wipefs_ctx handle"
  48 .Fa "off_t blockoff"
  49 .Fa "off_t nblocks"
  50 .Fc
  51 .Ft int
  52 .Fo wipefs_wipe
  53 .Fa "wipefs_ctx handle"
  54 .Fc
  55 .Ft void
  56 .Fo wipefs_free
  57 .Fa "wipefs_ctx *handlep"
  58 .Fc
  59 .Sh DESCRIPTION          \" Section Header - required - don't modify
  60 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.
  61 .Pp
  62 The
  63 .Fn wipefs_alloc
  64 function initializes a
  65 .Fa wipefs_ctx
  66 object (which is an opaque data type).
  67 .Fa file_desc
  68 is the file handle of the volume to be wiped, which can be a block device node, a character device node, or a file.
  69 .Fa file_desc
  70 must be opened with write access.  If
  71 .Fa block_size
  72 is 0, this function calls
  73 .Xr ioctl 2
  74 to get the block size.  A valid
  75 .Fa block_size
  76 must be supplied if
  77 .Fa file_desc
  78 is a regular file.  This function does not write any data to the volume.
  79 .Pp
  80 The
  81 .Fn wipefs_except_blocks
  82 function tells wipefs not to write anything in the block range provided.  This function is used for performance
  83 optimizations if the caller will write to these blocks.  It is the caller's responsibility to write to these blocks.
  84 Otherwise, some file systems may still be recognized on the volume.  This function does not write any data to the
  85 volume.  If this function is called multiple times, the union of all the ranges provided will be excluded from being
  86 written by
  87 .Fn wipefs_wipe .
  88 .Pp
  89 The
  90 .Fn wipefs_wipe
  91 function writes data to the volume to wipe out existing file systems on it.
  92 .Cm Caution:
  93 this function destroys any file system or partition scheme on the volume represented by
  94 .Fa file_desc .
  95 If
  96 .Fa file_desc
  97 represents the entire disk (e.g. /dev/diskX), the partition map of the disk will be destroyed.  If
  98 .Fa file_desc
  99 represents a partition (e.g., /dev/diskXsY), only the file system in that partition is destroyed.  Although the partition scheme or file system on
 100 .Fa file_desc
 101 may be beyond repair after
 102 .Fn wipefs_wipe ,
 103 this function is not designed as a means to safely delete all data.  It is possible that some user data (or intact file systems in some partitions) may still be recovered.
 104 .Pp
 105 The
 106 .Fn wipefs_free
 107 function frees the allocated
 108 .Fa wipefs_ctx
 109 handle and set
 110 .Fa *handlep
 111 to NULL.
 112 .Sh RETURN VALUES
 113 The
 114 .Fn wipefs_alloc ,
 115 .Fn wipefs_except_blocks
 116 and
 117 .Fn wipefs_wipe
 118 functions return 0 on success, or will fail and return an error code.
 119 Each function may return
 120 .Fa ENOMEM
 121 if insufficient memory is available.  In addition, if
 122 .Fa block_size
 123 is not provided,
 124 .Fn wipefs_alloc
 125 may return any error
 126 .Xr ioctl 2
 127 returns;
 128 .Fn wipefs_wipe
 129 may return any error
 130 .Xr pwrite 2
 131 returns.
 132 .\" .Sh BUGS              \" Document known, unremedied bugs
 133 .\".Sh HISTORY           \" Document history if command behaves in a unique manner
 134 .\"The wipefs family of functions first appeared in Mac OS X Leopard (10.5.3).