---
name: "wipefs"
section: "3"
platform: "macos"
package: "libutil"
version: "73"
release: "macOS 26.5"
platforms: ["macos"]
url: "https://new.carta.tech/wipefs/3"
---

# wipefs(3)

wipes existing file systems on a volume

## NAME

**wipefs\_alloc** **,**
 **wipefs\_except\_blocks** **,**
 **wipefs\_wipe** **,**
 **wipefs\_free**
 – wipes existing file systems on a volume

## LIBRARY

library “libutil
”

## SYNOPSIS

⟨wipefs.h
⟩ *int*
 **wipefs\_alloc**
(*int fd*, 
, *size\_t block\_size*, 
, *wipefs\_ctx \*handle*, 
 *int*
 **wipefs\_include\_blocks**
(*wipefs\_ctx handle*, 
, *off\_t block\_offset*, 
, *off\_t nblocks*, 
 *int*
 **wipefs\_except\_blocks**
(*wipefs\_ctx handle*, 
, *off\_t block\_offset*, 
, *off\_t nblocks*, 
 *int*
 **wipefs\_wipe**
(*wipefs\_ctx handle*, 
 *void*
 **wipefs\_free**
(*wipefs\_ctx \*handle*,

## DESCRIPTION

The wipefs family of functions wipe existing file systems on a volume.  A
 DKIOCUNMAP
 ioctl is sent to the device to invalidate all of its content.
 Then zeroes are written to various locations that are used by various file systems to recognize their content and mount their volumes.
 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.
 **NOTE:**
 These routines do not overwrite all volume structures.
 These routines do not securely erase the previous content.
 They only overwrite enough to make sure that the normal utilities will no longer recognize any file system content.
 It is possible that previous file system content could be recovered by other means.
 The
 **wipefs\_alloc**
() function initializes a
 *wipefs\_ctx*
 object (which is an opaque data type).
 *file\_desc*
 is the file handle of the volume to be wiped, which can be a block device node, a character device node, or a file.
 *file\_desc*
 must be opened with write access.  If
 *block\_size*
 is 0, this function calls
 ioctl(2
) to get the block size.  A valid
 *block\_size*, 
 must be supplied if 
 *file\_desc*
 is a regular file.  This function does not write any data to the volume.
 The
 **wipefs\_include\_blocks**
() function tells wipefs to write zeroes in the block range provided, in addition to any other ranges
 it would normally write.  This may be more efficient than if the caller were to write this range
 separately, especially if the block range overlaps or is contiguous with other ranges that wipefs
 will write.  This function does not write any data to the volume.  If this function is called
 multiple times, the union of all the ranges provided will be written by
 **wipefs\_wipe**(*.*
) The
 **wipefs\_except\_blocks**
() function tells wipefs not to write anything in the block range provided.  This function is used for performance
 optimizations if the caller will write to these blocks.  It is the caller's responsibility to write to these blocks.
 Otherwise, some file systems may still be recognized on the volume.  This function does not write any data to the
 volume.  If this function is called multiple times, the union of all the ranges provided will be excluded from being
 written by
 **wipefs\_wipe**(*.*
) The
 **wipefs\_wipe**
() function sends a
 DKIOCUNMAP
 ioctl and then writes data to the volume to wipe out existing file systems on it.
 **CAUTION:**
 this function destroys any file system or partition scheme on the volume represented by
 *file\_desc*, *.*
 If
 *file\_desc*
 represents the entire disk (e.g. /dev/diskX), the partition map of the disk will be destroyed.  If
 *file\_desc*
 represents a partition (e.g., /dev/diskXsY), only the file system in that partition is destroyed.  Although the partition scheme or file system on
 *file\_desc*
 may be beyond repair after 
 **wipefs\_wipe**(*,*
) 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.
 The
 **wipefs\_free**
() function frees the allocated 
 *wipefs\_ctx*
 handle and set
 *\*handlep*
 to NULL.

## RETURN VALUES

The
 **wipefs\_alloc**(*,*
) **wipefs\_include\_blocks**(*,*
) **wipefs\_except\_blocks**
() and
 **wipefs\_wipe**
() functions return 0 on success, or will fail and return an error code.
 Each function may return
 *ENOMEM*
 if insufficient memory is available.  In addition, if
 *block\_size*
 is not provided,
 **wipefs\_alloc**
() may return any error
 ioctl(2
) returns;
 **wipefs\_wipe**
() may return any error
 pwrite(2
) returns.