Manual Pages for UNIX Darwin command on man hdiutil

HDIUTIL(1) BSD General Commands Manual HDIUTIL(1)

NAME

hhddiiuuttiill - manipulate disk images (attach, verify, burn, etc)

SYNOPSIS

hhddiiuuttiill verb [options]

DESCRIPTION

hhddiiuuttiill uses the DiskImages framework to manipulate disk images. Common verbs include aattttaacchh, ddeettaacchh, vveerriiffyy, ccrreeaattee, ccoonnvveerrtt, ccoommppaacctt, and bbuurrnn. The rest of the verbs are: hheellpp, iinnffoo, llooaadd, cchheecckkssuumm, cchhppaassss, eejjeecctt (historical synonym for ddeettaacchh), uunnffllaatttteenn, ffllaatttteenn, iimmaaggeeiinnffoo, iisseennccrryypptteedd, mmoouunntt (historical synonym for aattttaacchh), mmoouunnttvvooll, uunnmmoouunntt,,

pplluuggiinnss, uuddiiffrreezz, uuddiiffddeerreezz, iinntteerrnneett-eennaabbllee, rreessiizzee, sseeggmmeenntt,

mmaakkeehhyybbrriidd, and ppmmaapp/ppmmaapp22. CCOOMMMMOONN OOPPTTIIOONNSS The following option descriptions apply to all verbs:

-vveerrbboossee be verbose; default is less output. This option can help the

user decipher why a particular operation failed. At a minimum, the probing of any specified images will be detailed.

-qquuiieett minimize output in most cases. -ddeebbuugg and -vveerrbboossee negate

almost all of -qquuiieett's functionality.

-ddeebbuugg be very verbose. This option is good if a large amount of

information about what hhddiiuuttiill and the DiskImages framework are

doing is needed. -ddeebbuugg and -vveerrbboossee generate almost entirely

independent outputs. Many hhddiiuuttiill verbs understand the following options:

-pplliisstt provide result output in plist format. Other programs

invoking hhddiiuuttiill are expected to use -pplliisstt rather than

try to parse the usual output. The usual output will remain consistent but unstructured.

-ppuuppppeettssttrriinnggss provide progress output that is easy for another program

to parse. Any program trying to interpret hhddiiuuttiill's

progress should use -ppuuppppeettssttrriinnggss.

-ssrrcciimmaaggeekkeeyy key=value

specify a key/value pair for the disk image recognition

system. (-iimmaaggeekkeeyy is normally a synonym)

-ttggttiimmaaggeekkeeyy key=value

specify a key/value pair for any image created.

(-iimmaaggeekkeeyy is only a synonym if there is no input image).

-eennccrryyppttiioonn [AES-128|AES-256]

specify a particular type of encryption or, if not speci-

fied, the default encryption algorithm. Two default algo-

rithm is the AES cipher with a 128-bit key.

-ssttddiinnppaassss read a null-terminated passphrase from standard input. If

the standard input is a tty, the passphrase will be read

with readpassphrase(3). -ssttddiinnppaassss replaces -ppaasssspphhrraassee

though the latter is still supported for compatibility. Beware that the password will contain any newlines before

the NULL. See the EXAMPLES section.

-aaggeennttppaassss Used with pubkey option if you need to create an encrypted

image protected by both a public key and a password. A dialog will be shown prompting for a password. This may be

used instead of -ssttddiinnppaassss in this case. This behavior is

the default if not specifying -ppuubbkkeeyy

-rreeccoovveerr keychainfile

specify a keychain containing the secret corresponding to

the certificate specified with -cceerrttiiffiiccaattee when the image

was created). The correct alternate secret will unlock the image.

-cceerrttiiffiiccaattee certificatefile

specify a secondary access certificate for the image being created.

-ppuubbkkeeyy PK1,PK2,...,PKn

specify a list of public key hashes in ASCII hex for the image being created. The hash(s) will be used to locate a public key used to protect an encrypted image.

-ccaacceerrtt cert specify a certificate authority certificate. cert can be

either a PEM file or a directory of certificates processed

by crehash(1). See also --ccaappaatthh and --ccaacceerrtt in

curl(1).

-iinnsseeccuurreehhttttpp ignore SSL host validation failures. Useful for self-

signed servers for which the appropriate certificates are unavailable or if access to a server is desired when the server name doesn't match what is in the certificate.

-sshhaaddooww [shadowfile]

Use a shadow file in conjunction with the data in the image. This option prevents modification of the original

image and allows read-only images to be attached

read/write. When blocks are being read from the image, blocks present in the shadow file override blocks in the base image. All data written to the attached device will be redirected to the shadow file. If not specified,

-shadow defaults to image.shadow. If the shadow file does

not exist, it is created. Verbs accepting -sshhaaddooww also

accept -ccaacceerrtt and -iinnsseeccuurreehhttttpp.

Verbs that create images automatically append the correct extension to any filenames if the extension is not already present. The creation engine also examines the filename extension of the provided filename and changes its behavior accordingly. For example, a sparse image can be

created without specifying -type SPARSEBUNDLE simply by appending the

.sparsebundle extension to the provided filename. VVEERRBBSS

Each verb is listed with its description and individual arguments. Argu-

ments to the verbs can be passed in any order. A sector is 512 bytes. hheellpp display minimal usage information for each verb. hhddiiuuttiill verb

-hheellpp will provide full usage information for that verb.

aattttaacchh image [options] attach a disk image to the system as a device. aattttaacchh, like

hdid(8), will return information about an already-attached

image as if it had attached it. mmoouunntt is a synonym for aattttaacchh. Beware that an image freshly created and attached is treated

as a new removable device. See hdid(8) and the EXAMPLES sec-

tion below for more details.

NOTE: The format of the output from the attach command is sub-

ject to change from release to release. The normal output displays the disk node, content hint, and mountpoint (if any). In particular, script authors should NOT rely upon the content hint being the same for a given partition type; for instance, HFS partitions have the content hint "AppleHFS" on an image

with an Apple partition map and "48465300-0000-11AA-

AA11-0030654" on an image with a GUID partition map.

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -rreeccoovveerr, -iimmaaggeekkeeyy,

-sshhaaddooww, -ppuuppppeettssttrriinnggss, and -pplliisstt.

Options:

-rreeaaddoonnllyy force the resulting device to be read-only

-rreeaaddwwrriittee attempt to override the DiskImages frame-

work's decision to attach a particular

image read-only. For example, -rreeaaddwwrriittee

can be used to modify the HFS filesystem on a HFS/ISO hybrid CD image.

-nnookkeerrnneell attach with a helper process.

-kkeerrnneell attempt to attach this image without a

helper process; fail if not possible.

-nnoottrreemmoovvaabbllee prevent this image from being detached.

Only root can use this option.

-mmoouunntt required|optional|suppressed

indicate whether filesystems in the image should be mounted or not. OS X 10.2.x and earlier defaulted to optional behavior; the default is now required.

-nnoommoouunntt identical to -mmoouunntt suppressed.

-mmoouunnttrroooott path mount volumes in path instead of in

/Volumes. path must exist. Note that

mountpoint paths must be less than MNAMELEN

characters (90 as of this writing).

-mmoouunnttrraannddoomm path like -mmoouunnttrroooott, but mountpoint names are

randomized with mkdtemp(3). Note that

mountpoint paths must be less than MNAMELEN

characters (90 as of this writing).

-mmoouunnttppooiinntt path assuming only one volume, mount it at path

instead of in /Volumes. Note that mount-

point paths must be less than MNAMELEN

characters (90 as of this writing). See fstab(5) for ways a system administrator can make particular volumes automatically mount in particular filesystem locations by editing the file /etc/fstab.

-uunniioonn perform a union mount

-pprriivvaattee suppress mount notifications to the rest of

the system. Note that -pprriivvaattee can confuse

programs using the Carbon File Manager and should generally be avoided.

-nnoobbrroowwssee mark the volumes non-browsable in applica-

tions such as the Finder.

-oowwnneerrss on|off enable or disable owners for HFS+ volumes,

potentially overriding the system's default value for the volume.

-ddrriivveekkeeyy key=value

specify a key/value pair to be attached to the device in the IOKit registry. The following options have corresponding elements in the com.apple.frameworks.diskimages preferences domain and thus can be rendered in both the positive and the negative:

-[[nnoo]]vveerriiffyy do [not] suppress verification of the image.

By default, hhddiiuuttiill aattttaacchh verifies all images containing checksums before attaching them. To maintain backwards compatibility, hdid(8) does not attempt to verify images before attaching them.

-[[nnoo]]iiggnnoorreebbaaddcchheecckkssuummss

specify whether bad checksums should be ignored. The default is to abort when a bad checksum is detected.

-[[nnoo]]iiddmmee do [not] perform IDME actions on IDME

images. IDME actions are normally only per-

formed when a browser downloads and attaches an image.

-[[nnoo]]iiddmmeerreevveeaall do [not] reveal (in the Finder) the results

of IDME processing.

-[[nnoo]]iiddmmeettrraasshh do [not] put IDME images in the trash after

processing.

-[[nnoo]]aauuttooooppeenn do [not] auto-open volumes (in the Finder)

after attaching an image. By default, read-

only volumes are auto-opened in the Finder.

-[[nnoo]]aauuttooooppeennrroo do [not] auto-open read-only volumes.

-[[nnoo]]aauuttooooppeennrrww do [not] auto-open read/write volumes.

-[[nnoo]]aauuttooffsscckk do [not] force automatic file system check-

ing before mounting a disk image. If fsck is successful and the image can be written, fsck will only run once on any particular instance of an image.

ddeettaacchh devname [-ffoorrccee]

detach a disk image and terminate any associated hdid process. devname is a partial /dev node path (e.g. "disk1"). As of OS

X 10.4, devname can also be a mountpoint. If Disk Arbitra-

tion is running, ddeettaacchh will use it to unmount any filesystems and detach the image. If not, ddeettaacchh will attempt to unmount any filesystems and detach the image directly (using the `eject' ioctl). If Disk Arbitration is not running, it may be necessary to unmount the filesystems with umount(8) before detaching the image. eejjeecctt is a synonym for ddeettaacchh. Options:

-ffoorrccee Similar to umount -f. Unmounts any filesystems and

detaches the image, regardless of any open files on the image. vveerriiffyy image [options]

compute the checksum of a read-only (or compressed) image and

verify it against the value stored in the image. vveerriiffyy

accepts the common options -eennccrryyppttiioonn, -ssttddiinnppaassss,

-ssrrcciimmaaggeekkeeyy, -ppuuppppeettssttrriinnggss, and -pplliisstt.

ccrreeaattee sizespec image create a new image of the given size or from the provided

data. If image already exists, -oovv must be specified or

ccrreeaattee will fail. If image is attached, it must be detached

before it can be overwritten, even if -oovv is specified. To

make a cross-platform CD or DVD, use mmaakkeehhyybbrriidd. See also

EXAMPLES below.

The size specified is the size of the image to be created. Filesystem and partition layout overhead (64 sectors for the default SPUD layout on PPC machines, 80 sectors for the default GPTSPUD layout on Intel machines) will be deducted before space is made for user data in any volume on the image. Size specifiers:

-ssiizzee ??b|??k|??m|??g|??t??p|??e

Specify the size of the image in the style of

mkfile(8) with the addition of tera-, peta-, and

exa-bytes sizes (note that 'b' specifies a number

of sectors, not bytes). The larger sizes are use-

ful when creating large sparse images.

-sseeccttoorrss sectorcount

Specify the size of the image file in 512 byte sec-

tors.

-mmeeggaabbyytteess size

Specify the size of the image file in megabytes (1024*1024 bytes).

-ssrrccffoollddeerr source

Derive the image size from the the filesystem entity source and copy the contents of source to the resulting image. The filesystem type of the image volume will match that of the source as

closely as possible unless overridden with -ffss.

Other size specifiers, such as -ssiizzee, will override

the default (size of the source directory plus some padding for filesystem overhead), allowing for more or less free space in the resulting filesystem.

-ssrrccffoollddeerr copies file by file, creating a fresh

(theoretically defragmented) filesystem on the des-

tination image. Such an image would be good for

use with asr(8). -ssrrccddiirr is a synonym.

-ssrrccddeevviiccee device

specifies that the blocks of device should be used to create a new image. The image size will match the size of device. rreessiizzee can be used to adjust the size of a filesystem in any writable image.

Both -ssrrccddeevviiccee and -ssrrccffoollddeerr can run into errors

if there are bad blocks on a disk. One way around this problem is to write over the files in question in the hopes that the drive will remap the bad blocks when it notices them. Data will be lost, but the image creation operation will subsequently succeed.

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -cceerrttiiffiiccaattee,

-ppuubbkkeeyy, -pplliisstt, -iimmaaggeekkeeyy, -ttggttiimmaaggeekkeeyy, -ppuuppppeettssttrriinnggss, and

-pplliisstt.

-iimmaaggeekkeeyy di-sparse-puma-compatible=TRUE and -iimmaaggeekkeeyy

di-shadow-puma-compatible=TRUE will create, respectively,

sparse and shadow images that can be attached on OS X 10.1.

-iimmaaggeekkeeyy encrypted-encoding-version can select between ver-

sion 1 and version 2 of the encrypted encoding. The framework preferences have a corresponding key to change the default for all images. Version 2 is not compatible with OS X 10.2 but is more robust for SPARSE (UDSP) images. Version 1 is the

default for non-sparse images. As of OS X 10.4.7, sparse,

encrypted images always use version 2. General options:

-aalliiggnn alignment

specifies a size to which the final data parti-

tion will be aligned. The default is 4K.

-ttyyppee UDIF|SPARSE|SPARSEBUNDLE

UDIF is the default disk image type. If speci-

fied, a UDRW of the specified size will be cre-

ated. Specifying SPARSE creates a UDSP: a

read/write single-file image which expands as

is is filled with data. SPARSEBUNDLE creates a

UDSB: a read/write backed by a directory bun-

dle. The default for UDSP is to grow one megabyte at a time. The default for UDSB is to create band files of up to 128 MB.

ssppaarrssee-bbaanndd-ssiizzee can be used (with -iimmaaggeekkeeyy)

to specify the number of sectors that will be added each time the image grows. The maximum size of a sparse image (of either type) is bounded by the filesystem in the image, the partition map (if any). SPARSE images are additionally bounded by an internal limit of 128 petabytes. ccoommppaacctt can reclaim unused bands in a UDSP if it has an HFS+ filesystem on it. As an alternative to sparse images, a UDRW

can be resized with rreessiizzee. See USING PERSIS-

TENT SPARSE IMAGES below for more information.

-ffss filesystem

where filesystem is one of HFS+, HFS+J, HFSX,

HFS, MS-DOS, or UFS. -ffss will cause a filesys-

tem of the specified type to be written to the

image. -ffss may also change the default layout

if that particular filesystem is not native to an AppleHFS partition in an Apple Partition Map.

-vvoollnnaammee volname

The newly-created filesystem will be named

volname. The default name is `untitled'.

-uuiidd uid the root of the newly-created volume will be

owned by the given numeric user id. 99 maps to the magic `unknown' user (see hdid(8)).

-ggiidd gid the root of the newly-created volume will be

owned by the given numeric group id. 99 maps to `unknown'.

-mmooddee mode the root of the newly-created volume will have

mode (in octal) mode.

-[[nnoo]]aauuttoossttrreettcchh do [not] suppress automatically making

stretchable volumes when the volume size

crosses the auto-stretch-size threshold

(default: 256 MB). See also asr(8).

-ssttrreettcchh maxstretch

-ssttrreettcchh initializes HFS+ filesystem data such

that it can later be stretched on older systems (which could only stretch within predefined limits) using hhddiiuuttiill rreessiizzee or by asr(8).

maxstretch is specified like -ssiizzee.

-ffssaarrggss newfsargs

additional arguments to pass to whatever newfs

program is implied by -ffss. newfshfs(8) has a

number of options that can reduce the amount of

space needed by the filesystem's data struc-

tures. Suppressing the journal with -ffss HFS+

and passing arguments such as -c c=64,a=16,e=16

to -ffssaarrggss will minimize gaps at the front of

the filesystem, allowing rreessiizzee to squeeze more space from the filesystem. For truly optimal filesystems, mmaakkeehhyybbrriidd should be used.

-llaayyoouutt layout

Specify the partition layout of the image.

layout can be anything specified in Medi-

aKit.framework's MKDrivers.bundle. NONE cre-

ates an image with no partition map. When such an image is attached, a single /dev entry will be created (e.g. /dev/disk1). SPUD is an

acronym for Single Partition UDIF. SPUD cre-

ates an image with a DDM and an Apple Partition Scheme partition map with a single entry for an AppleHFS partition. GPTSPUD creates an image with a GUID Partition Scheme partition map with a single entry for an AppleHFS partition. When attached, multiple /dev entries will be created and the 2nd partition will be the data partition (e.g. /dev/disk1, /dev/disk1s1, /dev/disk1s2; the second partition is disk1s2).

Unless changed by -ffss, the default is SPUD on

PPC machines, and GPTSPUD on Intel machines.

Other layouts include "UNIVERSAL HD" and "UNI-

VERSAL CD" which add appropriate OS 9 driver partitions for those types of media. OS 9 drivers are not used by OS X nor by its Classic environment.

-ppaarrttiittiioonnTTyyppee partitiontype

Change the type of partition in a single-parti-

tion disk image. The default is AppleHFS, though if the layout is not specified, the appropriate partition scheme and type will be automatically chosen depending on the argument

to -ffss.

-oovv overwrite an existing file. The default is not

to overwrite existing files. See the note with ccrreeaattee about not being allowed to overwrite attached images.

-aattttaacchh attach the image after creating it (plain

aattttaacchh - use hhddiiuuttiill aattttaacchh for more options).

Note that if no filesystem is specified via

-ffss, the attach will fail per the default

aattttaacchh -mmoouunntt required behavior.

Image from source options (for -ssrrccffoollddeerr and -ssrrccddeevviiccee):

-ffoorrmmaatt format Specify the final image format. The default

when a source is specified is UDZO. format can be any of the format parameters used by ccoonnvveerrtt.

Options specific to -ssrrccddeevviiccee:

-sseeggmmeennttSSiizzee sizespec

Specify that the image should be written in

segments no bigger than sizespec (which fol-

lows -ssiizzee conventions).

Options specific to -ssrrccffoollddeerr:

-[[nnoo]]ccrroossssddeevv do [not] cross device boundaries on the source

filesystem.

-[[nnoo]]ssccrruubb do [not] skip temporary files when imaging a

volume with -ssrrccffoollddeerr. Scrubbing is the

default when the source is the root of a mounted volume. Scrubbed items include trashes, temporary directories, swap, etc.

-[[nnoo]]aannyyoowwnneerrss do [not] require that the user invoking

hhddiiuuttiill own all of the files in the source.

-ccooppyyuuiidd user perform the copy as the given user. Normally,

the copy is performed to maintain fidelity as explained below.

-sskkiippuunnrreeaaddaabbllee skip files that can't be read by the copying

user and don't authenticate.

By default, ccrreeaattee -ssrrccffoollddeerr attempts to maintain the permis-

sions present in the source directory. It prompts for authen-

tication if it detects an unreadable file, a file owned by someone other than the user creating the image, or a SGID file in a group that the copying user is not in.

ccoonnvveerrtt image -ffoorrmmaatt format -oo outfile

convert image to type format and write the result to outfile. As mentioned above, the correct filename extension will be added only if it isn't part of the provided name. Format is one of:

UDRW - UDIF read/write image

UDRO - UDIF read-only image

UDCO - UDIF ADC-compressed image

UDZO - UDIF zlib-compressed image

UDBZ - UDIF bzip2-compressed image (OS X 10.4+ only)

UFBI - UDIF entire image with MD5 checksum

UDRo - UDIF read-only (obsolete format)

UDCo - UDIF compressed (obsolete format)

UDTO - DVD/CD-R master for export

UDxx - UDIF stub image

UDSP - SPARSE (grows with content)

UDSB - SPARSEBUNDLE (grows with content; bundle-backed)

RdWr - NDIF read/write image (deprecated)

Rdxx - NDIF read-only image (Disk Copy 6.3.3 format)

ROCo - NDIF compressed image (deprecated)

Rken - NDIF compressed (obsolete format)

DC42 - Disk Copy 4.2 image

In addition to the compression offered by some formats, the

UDIF and NDIF read-only formats completely remove unused space

in HFS and UFS filesystems. For UDZO, -iimmaaggeekkeeyy

zlib-level=value allows the zlib compression level to be spec-

ified ala gzip(1). The default compression level is 1 (fastest). Options are any of:

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -cceerrttiiffiiccaattee,

-ssrrcciimmaaggeekkeeyy, -ttggttiimmaaggeekkeeyy, -sshhaaddooww with friends,

-ppuuppppeettssttrriinnggss, and -pplliisstt.

Other options:

-aalliiggnn alignment

The default is 4 (2K).

-ppmmaapp add partition map.

When converting a NDIF to a any variety of UDIF, or when converting an unpartitioned UDIF, the default is true.

-sseeggmmeennttSSiizzee [sizespec]

Specify segmentation into sizespec-sized seg-

ments as outfile is being written. The default

sizespec when -sseeggmmeennttSSiizzee is specified alone is

2*1024*1024 (1 GB worth of sectors) for UDTO images and 4*1024*1024 (2 GB segments) for all

other image types. sizespec can also be speci-

fied ??b|??k|??m|??g|??t??p|??e like ccrreeaattee's

-ssiizzee flag.

-ttaasskkss taskcount

When converting an image into a compressed for-

mat, specify the number of threads to use for the compression operation. The default is the number of processors active in the current system. bbuurrnn image Burn image to optical media in an attached burning device. In

all cases, a prompt for media will be printed once an appro-

priate drive has been found. Common options: -sshhaaddooww with

friends, -ssrrcciimmaaggeekkeeyy, -eennccrryyppttiioonn, -ppuuppppeettssttrriinnggss, and

-ssttddiinnppaassss.

Other options:

-ddeevviiccee specify a device to use for burning. See

-lliisstt.

-tteessttbbuurrnn don't turn on laser (laser defaults to on).

-aannyyddeevviiccee explicitly allow burning to devices not qual-

ified by Apple (kept for backwards compati-

bility as bbuurrnn will burn to any device by default as of OS X 10.4).

-[[nnoo]]eejjeecctt do [not] eject disc after burning. The

default is to eject the disc.

-[[nnoo]]vveerriiffyybbuurrnn do [not] verify disc contents after burn.

The default is to verify.

-[[nnoo]]aaddddppmmaapp do [not] add partition map if necessary.

Some filesystem types will not be recognized when stored on optical media unless they are enclosed in a partition map. This option

will add a partition map to any bare filesys-

tem which needs a partition map in order to be recognized when burned to optical media. The default is to add the partition map if needed.

-[[nnoo]]sskkiippffiinnaallffrreeee do [not] skip final free partition. If

there is a partition map on the image speci-

fying an AppleFree partition as the last partition, that AppleFree partition will not be burned. The burned partition map will still reference the empty space. The default is to skip burning a final free partition.

-[[nnoo]]ooppttiimmiizzeeiimmaaggee do [not] optimize filesystem for burning.

Optimization can reduce the size of an HFS or HFS+ volume to the size of the data contained on the volume. This option will change what

is burned such that the disc will have a dif-

ferent checksum than the image it came from. The default is to burn all blocks of the disk image (minus any trailing AppleFree).

-[[nnoo]]ffoorrcceecclloossee do [not] force the disc to be closed after

burning. Further burns to the disc will be impossible. The default is not to close the disc.

-nnoouunnddeerrrruunn Disable the default buffer underrun protec-

tion.

-[[nnoo]]ssyynntthheessiizzee [Don't] Synthesize a hybrid filesystem for

the disc. The default is to create a new (HFS/ISO) filesystem when the source image's blocks could not be legally burned to a disc.

-ssppeeeedd xfactor 1, 2, 4, 6, ... `max'

The desired "x-factor". e.g. 8 means the

drive will be instructed burn at "8x speed". `max' will cause the burn to proceed at the maximum speed of the drive. `max' is the default speed. Slower speeds can produce more reliable burns. The speed factor is relative to the media being burned (e.g.

-ssppeeeedd 2 has a different data rate when used

for a DVD burn vs. a CD burn). Note that some drives have a minimum burn speed in which case any slower speed specified will result in a burn at the drive's minimum speed.

-ssiizzeeqquueerryy calculate the size of disc required (the size

returned is in sectors) without burning any-

thing.

-eerraassee prompt for optical media (DVD-RW/CD-RW) and

then, if the hardware supports it, quickly erase the media. If an image is specified, it will be burned to the media after the media has been erased.

-ffuulllleerraassee erase all sectors of the disc (this usually

takes quit a bit longer than -eerraassee).

-lliisstt list all burning devices, with OpenFirmware

paths suitable for -ddeevviiccee.

mmaakkeehhyybbrriidd -oo image source

Generate a potentially-hybrid filesystem in a read-only disk

image using the DiscRecording framework's content creation system.

source can either be a directory or a disk image. The gener-

ated image can later be burned using bbuurrnn, or converted to

another read-only format with ccoonnvveerrtt. By default, the

filesystem will be readable on most modern computing plat-

forms. The generated filesystem is not intended for conver-

sion to read/write, but can safely have its files copied to a

read/write filesystem by ditto(8) or asr(8) (in file-copy

mode).

hhddiiuuttiill supports generating El Torito-style bootable ISO9660

filesystems, which is commonly used for booting x86-based

hardware. The specification includes several emulation modes. By default, an El Torito boot image emulates either a 1.2MB, 1.44MB, or 2.88MB floppy drive, depending on the size of the image. Also available are "No Emulation" and "Hard Disk Emulation" modes, which allow the boot image to either be

loaded directly into memory, or be virtualized as a parti-

tioned hard disk, respectively. The El Torito options should not be used for data CDs. Filesystem options:

-hhffss Generate an HFS+ filesystem. This filesystem can be

present on an image simultaneously with an ISO9660 or Joliet or UDF filesystem. On operating systems that understand HFS+ as well as ISO9660 and UDF, like Mac

OS 9 or Mac OS X, it is usually the preferred filesys-

tem.

-iissoo Generate an ISO9660 Level 2 filesystem with Rock Ridge

extensions. This filesystem can be present on an image simultaneously with an HFS+ or Joliet or UDF

filesystem. ISO9660 is the standard cross-platform

interchange format for CDs and some DVDs, and is understood by virtually all operating systems. If an ISO9660 or Joliet filesystem is present on a disk image or CD, but not HFS+, Mac OS X will use the ISO9660 (or Joliet) filesystem.

-jjoolliieett Generate Joliet extensions to ISO9660. This view of

the filesystem can be present on an image simultane-

ously with HFS+, and requires the presence of an

ISO9660 filesystem. Joliet supports Unicode file-

names, but is only supported on some operating sys-

tems. If both an ISO9660 and Joliet filesystem are present on a disk image or CD, but not HFS+, Mac OS X will prefer the Joliet filesystem.

-uuddff Generate a UDF filesystem. This filesystem can be

present on an image simultaneously with HFS+, ISO9660, and Joliet. UDF is the standard interchange format for DVDs, although operating system support varies based on OS version and UDF version. By default, if no filesystem is specified, the image will be created with all four filesystems as a hybrid image. When multiple filesystems are selected, the data area of the image

is shared between all filesystems, and only directory informa-

tion and volume meta-data are unique to each filesystem. This

means that creating a cross-platform ISO9660/HFS+ hybrid has a

minimal overhead when compared to a single filesystem image. Other options (most take a single argument):

-hhffss-bblleesssseedd-ddiirreeccttoorryy Path to directory which should be

"blessed" for Mac OS X booting on the generated filesystem. This assumes the directory has been otherwise prepared,

for example with bless -bboooottiinnffoo to

create a valid BootX file. (HFS+ only).

-hhffss-ooppeennffoollddeerr Path to a directory that will be opened

by the Finder automatically. See also

the -ooppeennffoollddeerr option in bless(8)

(HFS+ only).

-hhffss-ssttaarrttuuppffiillee-ssiizzee Allocate an empty HFS+ Startup File of

the specified size, in bytes (HFS+ only).

-aabbssttrraacctt-ffiillee Path to a file in the source directory

(and thus the root of the generated filesystem) for use as the ISO9660/Joliet Abstract file (ISO9660/Joliet).

-bbiibblliiooggrraapphhyy-ffiillee Path to a file in the source directory

(and thus the root of the generated filesystem) for use as the ISO9660/Joliet Bibliography file (ISO9660/Joliet).

-ccooppyyrriigghhtt-ffiillee Path to a file in the source directory

(and thus the root of the generated filesystem) for use as the ISO9660/Joliet Copyright file (ISO9660/Joliet).

-aapppplliiccaattiioonn Application string (ISO9660/Joliet).

-pprreeppaarreerr Preparer string (ISO9660/Joliet).

-ppuubblliisshheerr Publisher string (ISO9660/Joliet).

-ssyysstteemm-iidd System Identification string

(ISO9660/Joliet).

-kkeeeepp-mmaacc-ssppeecciiffiicc Expose Macintosh-specific files (such

as .DSStore) in non-HFS+ filesystems

(ISO9660/Joliet).

-eellttoorriittoo-bboooott Path to an El Torito boot image. By

default, floppy drive emulation is used, so the image must be one of 1200KB, 1440KB, or 2880KB. If the image has a different size, either

-nnoo-eemmuull-bboooott or -hhaarrdd-ddiisskk-bboooott must

be used to enable "No Emulation" or

"Hard Disk Emulation" mode, respec-

tively (ISO9660/Joliet).

-hhaarrdd-ddiisskk-bboooott Use El Torito Hard Disk Emulation mode.

The image must represent a virtual device with an MBR partition map and a single partition

-nnoo-eemmuull-bboooott Use El Torito No Emulation mode. The

system firmware will load the number of

sectors specified by -bboooott-llooaadd-ssiizzee

and execute it, without emulating any devices (ISO9660/Joliet).

-nnoo-bboooott Mark the El Torito image as non-

bootable. The system firmware may still create a virtual device backed by this data. This option is not recommended (ISO9660/Joliet).

-bboooott-llooaadd-sseegg For a No Emulation boot image, load the

data at the specified segment address. This options is not recommended, so that the system firmware can use its default address (ISO9660/Joliet)

-bboooott-llooaadd-ssiizzee For a No Emulation boot image, load the

specified number of 512-byte emulated

sectors into memory and execute it. By default, 4 sectors (2KB) will be loaded (ISO9660/Joliet).

-eellttoorriittoo-ppllaattffoorrmm Use the specified numeric platform ID

in the El Torito Boot Catalog Valida-

tion Entry or Section Header. Defaults to 0 to identify x86 hardware (ISO/Joliet).

-eellttoorriittoo-ssppeecciiffiiccaattiioonn For complex layouts involving multiple

boot images, a plist-formatted string

can be provided, using either OpenStep-

style syntax or XML syntax, represent-

ing an array of dictionaries. Any of the El Torito options can be set in the

sub-dictionaries and will apply to that

boot image only. If

-eellttoorriittoo-ssppeecciiffiiccaattiioonn is provided in

addition to the normal El Torito com-

mand-line options, the specification

will be used to populate secondary non-

default boot entries.

-uuddff-vveerrssiioonn Version of UDF filesystem to generate.

This can be either "1.02" or "1.50". If not specified, it defaults to "1.50" (UDF).

-ddeeffaauulltt-vvoolluummee-nnaammee Default volume name for all filesys-

tems, unless overridden. If not speci-

fied, defaults to the last path compo-

nent of source.

-hhffss-vvoolluummee-nnaammee Volume name for just the HFS+ filesys-

tem if it should be different (HFS+ only).

-iissoo-vvoolluummee-nnaammee Volume name for just the ISO9660

filesystem if it should be different (ISO9660 only).

-jjoolliieett-vvoolluummee-nnaammee Volume name for just the Joliet

filesystem if it should be different (Joliet only).

-uuddff-vvoolluummee-nnaammee Volume name for just the UDF filesystem

if it should be different (UDF only).

-hhiiddee-aallll A glob expression of files and directo-

ries that should not be exposed in the generated filesystems. The string may

need to be quoted to avoid shell expan-

sion, and will be passed to glob(3) for

evaluation. Although this option can-

not be used multiple times, an arbi-

trarily complex glob expression can be used.

-hhiiddee-hhffss A glob expression of files and directo-

ries that should not be exposed via the HFS+ filesystem, although the data may still be present for use by other filesystems (HFS+ only).

-hhiiddee-iissoo A glob expression of files and directo-

ries that should not be exposed via the ISO filesystem, although the data may still be present for use by other filesystems (ISO9660 only). Per above, the Joliet hierarchy will supersede the ISO hierarchy when the hybrid is mounted as an ISO 9660 filesystem on Mac OS X. Therefore, if Joliet is being generated (the default)

-hhiiddee-jjoolliieett will also be needed to

hide the file from mountcd9660(8).

-hhiiddee-jjoolliieett A glob expression of files and directo-

ries that should not be exposed via the Joliet filesystem, although the data may still be present for use by other filesystems (Joliet only). Because OS X's ISO 9660 filesystem uses the Joliet catalog if it is available,

-hhiiddee-jjoolliieett effectively supersedes

-hhiiddee-iissoo when the resulting filesystem

is mounted as ISO on OS X.

-hhiiddee-uuddff A glob expression of files and directo-

ries that should not be exposed via the UDF filesystem, although the data may still be present for use by other filesystems (UDF only).

-oonnllyy-uuddff A glob expression of objects that

should only be exposed in UDF.

-oonnllyy-iissoo A glob expression of objects that

should only be exposed in ISO.

-oonnllyy-jjoolliieett A glob expression of objects that

should only be exposed in Joliet.

-pprriinntt-ssiizzee Preflight the data and calculate an

upper bound on the size of the image. The actual size of the generated image is guaranteed to be less than or equal to this estimate.

-pplliissttiinn Instead of using command-line parame-

ters, use a standard plist from stan-

dard input to specific the parameters of the hybrid image generation. Each

command-line option should be a key in

the dictionary, without the leading

"-", and the value should be a string

for path and string arguments, a number for number arguments, and a boolean for toggle options. The source argument should use a key of "source" and the image should use a key of "output". If a disk image was specified for source, the image will be

attached and paths will be evaluated relative to the mount-

point of the image. No absolute paths can be used in this case. If source is a directory, all argument paths should point to files or directories either via an absolute path, or via a relative path to the current working directory. The volume name options, just like files in the filesystems, may need to be mapped onto the legal character set for a given filesystem or otherwise changed to obey naming restrictions. Use drutil(1) as ddrruuttiill ffiilleennaammee myname to see how a given string would be remapped.

The -aabbssttrraacctt-ffiillee, -bbiibblliiooggrraapphhyy-ffiillee, -aanndd -ccooppyyrriigghhtt-ffiillee

must exist directly in the source directory, not a sub-direc-

tory, and must have an 8.3 name for compatibility with ISO9660 Level 1. ccoommppaacctt image scans the bands of a sparse (SPARSE or SPARSEBUNDLE) disk image containing an HFS filesystem, removing those parts of the image which are no longer being used by the filesystem. Depending on the location of files in the hosted filesystem, ccoommppaacctt may or may not shrink the image. For SPARSEBUNDLE images, completely unused band files are simply removed.

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -ssrrcciimmaaggeekkeeyy, -sshhaaddooww

with friends, -ppuuppppeettssttrriinnggss, and -pplliisstt.

iinnffoo display information about DiskImages.framework, the disk image driver, and any images that are currently attached. hhddiiuuttiill

iinnffoo accepts -pplliisstt.

llooaadd manually load the disk image driver. Normally, the disk image driver is loaded by the DiskImages framework whenever needed. As of OS X 10.2, the driver will automatically unregister itself after the last image is detached (it will then be unloaded after about a minute without being used again).

cchheecckkssuumm image -ttyyppee type

Calculate the specified checksum on the image data, regardless of image type.

Common options: -sshhaaddooww with friends, -eennccrryyppttiioonn, -ssttddiinnppaassss.

-ssrrcciimmaaggeekkeeyy, -ppuuppppeettssttrriinnggss, and -pplliisstt,

type is one of:

UDIF-CRC32 - CRC-32 image checksum

UDIF-MD5 - MD5 image checksum

DC42 - Disk Copy 4.2

CRC28 - CRC-32 (NDIF)

CRC32 - CRC-32

MD5 - MD5

SHA - SHA

SHA1 - SHA-1

SHA256 - SHA-256

SHA384 - SHA-384

SHA512 - SHA-512

cchhppaassss image change the passphrase for an encrypted image. The default is to change the password interactively.

Common options: -rreeccoovveerr and -ssrrcciimmaaggeekkeeyy. The options

-oollddssttddiinnppaassss and -nneewwssttddiinnppaassss allow, in the order specified,

the null-terminated old and new passwords to be read from the

standard input in the same manner as with -ssttddiinnppaassss.

uunnffllaatttteenn image

unflatten a UDIF disk image, creating a dual-fork file in tra-

ditional format (resource-only; no XML). If the resource fork

representation of the metadata becomes greater than 16 MB, the

operation will fail with error -39 ("End of fork").

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, and -ssrrcciimmaaggeekkeeyy.

ffllaatttteenn image

Flatten a read-only (or compressed) UDIF disk image into a

single-fork file. By default, metadata will be stored both as

XML (for the kernel's use) and in an embedded resource fork

(for OS X 10.1 and earlier). Note: UDBZ is not supported in-

kernel.

Common options: -ssrrcciimmaaggeekkeeyy, -eennccrryyppttiioonn, and -ssttddiinnppaassss.

ffllaatttteenn is only required if the UDIF has previously been uunnffllaatttteenned. Other options:

-nnooxxmmll don't embed XML data for in-kernel attachment.

The image will never attach in-kernel.

-nnoorrssrrccffoorrkk don't embed resource fork data. The image will

not attach on OS X versions prior to OS X 10.2. ffssiidd image Print information about file systems on a given disk image.

As is usually the case, image can be a /dev entry correspond-

ing to a physical disk. See the NOTE ON DEV ENTRY ACCESS sec-

tion. More detailed information is presented for HFS file systems.

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -ssrrcciimmaaggeekkeeyy, and

-sshhaaddooww with friends.

mmoouunnttvvooll devname

mount the filesystem in devname using Disk Arbitration (simi-

lar to diskutil(8)'s mmoouunntt). XML output is available from

-pplliisstt. Note that mmoouunnttvvooll (rather than mmoouunntt, though it

often works in OS X 10.5 and later) is the correct way to remount a volume after it has been unmounted by uunnmmoouunntt. Prior to OS X 10.5, mmoouunntt/aattttaacchh would treat a /dev entry as a disk image to be attached (creating another /dev entry). That behavior was undesirable.

uunnmmoouunntt volume [-ffoorrccee]

unmount a mounted volume without detaching any associated

image. Volume is a /dev entry or mountpoint. NOTE: uunnmmoouunntt

does NOT detach any disk image associated with the volume. Images are attached and detached; volumes are mounted and unmounted. mmoouunnttvvooll will remount a volume that has been unmounted by uunnmmoouunntt. Options:

-ffoorrccee unmount filesystem regardless of open files on that

filesystem. Similar to umount -f.

iimmaaggeeiinnffoo image Print out information about a disk image.

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -ssrrcciimmaaggeekkeeyy, -sshhaaddooww

with friends, and -pplliisstt.

Options are any of:

-ffoorrmmaatt just print out the image format

-cchheecckkssuumm just print out the image checksum

iisseennccrryypptteedd image print a line indicating whether image is encrypted. If it is, additional details are printed.

Common options: -pplliisstt.

pplluuggiinnss print information about DiskImages framework plugins. The user, system, local, and network domains are searched for

plugins (i.e. ~/Library/Plug-ins/DiskImages,

/System/Library/Plug-ins/DiskImages,

/Library/Plug-ins/DiskImages,

/Network/Library/Plug-ins/DiskImages).

Common options: -pplliisstt.

iinntteerrnneett-eennaabbllee [-yyeess] | -nnoo | -qquueerryy image

Enable or disable post-processing for the image. Without

arguments, IDME will be enabled. If so enabled, upon first encounter with Disk Copy (on OS X 10.2.3+) or a browser using the feature for a download on OS X 10.3, the image will have its visible contents copied into the directory containing the image and the image will be put into the trash with IDME turned off.

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -ssrrcciimmaaggeekkeeyy, and

-pplliisstt.

rreessiizzee sizespec image Resize a disk image or the containers within it. Given a read/write partitioned UDIF, if the last partition is AppleHFS, attempt to resize the partition to the end of the image, or to the last used block in the embedded HFS/HFS+ filesystem (depending on sizespec). On older systems, rreessiizzee

was limited to pre-defined limits that depended on how the

filesystem was created. As of OS X 10.4, rreessiizzee can be used

to grow an HFS filesystem within an image to any size sup-

ported by HFS and the filesystem hosting the image. rreessiizzee is often used when a device image needs to be shrunk so

that the HFS/HFS+ partition can be converted to CD-R/DVD-R

format and still be burned. Note that gaps cannot be

reclaimed as rreessiizzee does not move data. -ffssaarrggss can sometimes

be used to minimize filesystem-generated gaps. rreessiizzee can

grow a filesystem and image within the bounds of the image and filesystem formats (e.g. roughly 2^63 bytes for HFS+ inside of a UDRW on HFS+). hhddiiuuttiill bbuurrnn does not burn AppleFree partitions at the end of the devices, so an image with a resized filesystem can be

burned to create a CD-R/DVD-R master that contains only the

actual data in the hosted filesystem (assuming minimal data fragmentation).

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -ssrrcciimmaaggeekkeeyy, -sshhaaddooww

with friends, and -pplliisstt.

Size specifiers:

-ssiizzee ??b|??k|??m|??g|??t??p|??e

-sseeccttoorrss sectorcount | min | max

Specify the number of 512 byte sectors to which the partition should be resized. If this falls outside the min/max values, an error will be returned and the partition will not be resized. min automatically determines the smallest size the partition can be

resized to and uses that value. max automat-

ically determines the largest size to which the partition can be grown and then uses that value. Other options:

-iimmaaggeeoonnllyy only resize the image file, not the parti-

tion(s) inside of it. This is the default for UDIF images (more partitions can then be added in the new free space).

-ppaarrttiittiioonnoonnllyy only resize the partition(s) in the image

(including their embedded filesystems). This

is the default for NDIF images. For a newly-

created single partition disk image where the partition fills the image, the partition can only be shrunk. If there is an AppleFree partition after an existing partition, that partition can be expanded into the space

marked by the AppleFree. Shrinking a parti-

tion results in a larger AppleFree parti-

tion.

-ppaarrttiittiioonnNNuummbbeerr partitionNumber

specifies which partition to resize (UDIF

only - see HISTORY below). partitionNumber

is 0-based, but, per hhddiiuuttiill ppmmaapp, partition

0 is the partition map itself.

-ggrroowwoonnllyy only allow the image to grow

-sshhrriinnkkoonnllyy only allow the image to shrink

-nnooffiinnaallggaapp allow resize to entirely eliminate the trail-

ing free partition. Such an image restored to a hard drive will not boot OS 9 nor will

it allow OS X to boot on old-world (beige)

machines.

-lliimmiittss Displays the minimum, current, and maximum

sizes (in 512 byte sectors) that could be

passed given possible -iimmaaggeeoonnllyy or

-ppaarrttiittiioonnoonnllyy flags. In addition to any

filesystem constraints, the maximum size is limited by available disk space for UDRW images. Does not modify the image.

-oollddlliimmiittss behaves like -lliimmiittss except that it reports

the stretch sizes that OS X version 10.3 would have reported (useful if an image needs to be used with asr(8) on an older system). sseeggmmeenntt

sseeggmmeenntt -oo firstSegname -sseeggmmeennttCCoouunntt #segs image [opts]

sseeggmmeenntt -oo firstSegname -sseeggmmeennttSSiizzee size image [opts]

segment a NDIF or UDIF disk image. Segmented images work around limitations in file size which are sometimes imposed by filesystems, network protocols, or media. Note: whether or not the segments are encrypted is determined by the options passed to sseeggmmeenntt and not by the state of the source image.

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -ssrrcciimmaaggeekkeeyy,

-ttggttiimmaaggeekkeeyy, -ppuuppppeettssttrriinnggss, and -pplliisstt.

Options:

-sseeggmmeennttCCoouunntt segmentcount

Specify the number of segments. Only one of

-sseeggmmeennttCCoouunntt or -sseeggmmeennttSSiizzee will be honored.

-sseeggmmeennttSSiizzee segmentsize

Specify the segment size in sectors or in the style of mkfile(8) (here unqualified numbers are still sectors). If the original image size is not an exact multiple of the segment size, the last segment will be shorter than the others.

Only one of -sseeggmmeennttCCoouunntt or -sseeggmmeennttSSiizzee will be

honored. Segmenting read/write (UDRW) images is not supported (as of OS X 10.3).

-ffiirrssttSSeeggmmeennttSSiizzee segmentsize

Specify the first segment size in sectors in the

same form as for -sseeggmmeennttSSiizzee. Used for multi-CD

restores.

-rreessttrriicctteedd Make restricted segments for use in multi-CD

restores.

-oovv overwrite any existing files. See notes with

ccrreeaattee about not being allowed to overwrite attached images, etc.

ppmmaapp imagesource [-ooppttiioonnss optstr]

display the partition map of an image or device. imagesource is either a plain file or special file (i.e. a /dev/disk

entry). See the NOTE ON DEV ENTRY ACCESS below.

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -ssrrcciimmaaggeekkeeyy, and

-sshhaaddooww with friends.

optstr defaults to "xsSgcvk" and can be any combination of the following:

r raw - process all without modification

x extended - process 2K & 512 entries and merge

s sectorize - return all quantities in sectors

S sort - sort all entries by block number

g genfree - account for all unmapped space

c combfree - combine adjacent freespace entries

f fixfinal - extend last partition to device end

v volume synthesize - synthesize single volumes as

a single partition entry

k skip zero-length - skip zero length entries

K skip void/free - skip all free & void partitions

m merge free space - Merge small free partitions into

a previous partition if possible

i ignore shims - ignore small free partitions

caused by block alignment ppmmaapp22 [options] imagesource display a verbose partition map for imagesource. Supports GUID Partition Scheme maps.

Common Options: -eennccrryyppttiioonn, -ssttddiinnppaassss, -ssrrcciimmaaggeekkeeyy, and

-sshhaaddooww with friends.

uuddiiffrreezz [options] image embed resources (e.g. a software license agreement) in a disk image. You must specify one of the following options:

-xxmmll file

Copy resources from the XML in file.

-rrssrrccffoorrkk file

Copy resources from file's resource fork.

-rreeppllaacceeaallll

Delete all pre-existing resources in image.

uuddiiffddeerreezz [options] image extract resources from image. Options:

-xxmmll emit XML output (default)

-rreezz emit Rez format output

Common options: -eennccrryyppttiioonn, -ssttddiinnppaassss, and -ssrrcciimmaaggeekkeeyy.

EEXXAAMMPPLLEESS Verifying:

hdiutil verify myimage.img

Verifies an image against its internal checksum. Segmenting:

hdiutil segment -segmentSize 10m -o /tmp/aseg 30m.dmg

creates aseg.dmg, aseg.002.dmgpart, and aseg.003.dmgpart Converting:

hdiutil convert master.dmg -format UDTO -o master

Converts master.dmg to a CD-R export image, appending

.toast to the filename.

hdiutil convert CDmaster.dmg -format UDTO -o CDmaster.cdr

Converts CDmaster.dmg to a CD-R export image named

CDmaster.cdr.

hdiutil convert /dev/disk1 -format UDRW -o devimage

Converts the disk /dev/disk1 to a read/write device image file. authopen(1) will be used if read access to

/dev/rdisk1 is not available. Note use of the block-special

device. Burning:

hdiutil burn myImage.dmg

Burns the image to available optical media and verifies the burn.

hdiutil burn myRawImage.cdr -noverifyburn -noeject

Burns the image without verifying the burn or ejecting the disc. Volumes will be mounted after burning. Creating a 50 MB encrypted image:

hdiutil create -encryption -size 50m e.dmg -fs HFS+J

Creating a 50 MB encrypted image protected with public key only:

hdiutil create -encryption -size 50m e.dmg -fs HFS+J

-pubkey F534A3B0C2AEE3B988308CC89AA04ABE7FDB5F30

Creating a 50 MB encrypted image protected with public key and password:

hdiutil create -encryption -size 50m e.dmg -fs HFS+J -agentpass

-pubkey F534A3B0C2AEE3B988308CC89AA04ABE7FDB5F30

Creating an encrypted single-partition (Apple Partition Map on PPC and

GUID Partition Scheme on Intel) disk image without user interaction:

echo -n pp|hdiutil create -encryption -stdinpass -size 9m sp.dmg

Creating a "1 GB" SPARSE image (a 1 GB filesystem in a growable file):

hdiutil create -type SPARSE -size 1g -fs HFS+ growableTo1g

Creating a "1 GB" SPARSEBUNDLE (a 1 GB filesystem in a growable bundle):

hdiutil create -type SPARSEBUNDLE -size 1g -fs HFS+ growableTo1g

Creating a new mounted volume backed by an image:

hdiutil create -volname Dick -size 1.3m -fs HFS -attach Moby.dmg

Using a shadow file to attach a read-only image read-write to modify it,

then convert it back to a read-only image. This method eliminates the

time/space required to convert a image to read-write before modifying it.

hdiutil attach -owners on Moby.dmg -shadow

/dev/disk2 Applepartitionscheme /dev/disk2s1 Applepartitionmap /dev/disk2s2 AppleHFS /Volumes/Moby ditto /Applications/Preview.app /Volumes/Moby

hdiutil detach /dev/disk2

hdiutil convert -format UDZO Moby.dmg -shadow

Using makehybrid. Given the files: albumlist.txt song2.wma song4.m4a song6.mp3 song8.mp3 song1.wma song3.m4a song5.mp3 song7.mp3 Create an HFS+/ISO9660/Joliet hybrid MusicBackup.iso with some common content between filesystems. The HFS+ filesystem, typically only visible on Macintosh systems, will not include the .wma files, but will show the .m4a and .mp3 files. The Joliet filesystem will not show the .m4a and

.mp3 files, but will show the .wma files. The ISO9660 filesystem, typi-

cally the default filesystem for optical media on many platforms, will

only show the .mp3 files. All three filesystems will include the "album-

list.txt" files. The -hide options take glob expressions as expanded by

glob(3).

hdiutil makehybrid -o MusicBackup.iso Music -hfs -iso -joliet \

-hide-hfs 'Music/*.wma' -hide-joliet 'Music/{*.m4a,*.mp3}' \

-hide-iso 'Music/*.{wma,m4a}'

(see also drutil(1) for making CD audio discs)

Image from directory (new-style):

hdiutil create -srcfolder mydir mydir.dmg

Image from directory (10.1-style; of historical interest):

du -s myFolder # du(1) will count resource forks

10542

hdiutil create -sectors 10642 folder # add ~1% for filesytem

hdid -nomount folder.dmg

... /dev/disk1s2 AppleHFS

newfshfs -v myFolderImage /dev/rdisk1s2

hdiutil detach disk1

hdid folder.dmg ... /dev/disk1s2 AppleHFS /Volumes/myFolderImage

sudo mount -u -t hfs -o perm /dev/disk1s2 /Volumes/myFolderImage

# optionally enable owners; sudo unneeded if manually mounted

ditto -rsrcFork myFolder /Volumes/myFolderImage

hdiutil detach disk1s2 # all done

hdiutil convert -format UDZO -o folder.z.dmg folder.dmg # compress

Manually changing ownership settings of a read-only disk image:

hdiutil attach myimage.dmg

... /dev/disk1s2 AppleHFS /Volumes/myVolume

sudo mount -ur -t hfs -o perm /dev/disk1s2 /Volumes/myVolume

# what if I prefer using /sbin/mount

disktool -p disk1s2 # try 'diskutil unmount' on Panther

mkdir /Volumes/myVolume Forcing a known image to attach:

hdiutil attach -imagekey diskimage-class=CRawDiskImage myBlob.bar

ENVIRONMENT The following environment variables affect hhddiiuuttiill and DiskImages: comapplehdidverbose

enable -vveerrbboossee behavior for aattttaacchh.

comapplehdiddebug

enable -ddeebbuugg behavior for aattttaacchh.

comapplehdidnokernel

similar to -nnookkeerrnneell but works even with, for example, ccrreeaattee

-aattttaacchh.

comapplehdidkernel

attempt to attach in-kernel first (like aattttaacchh -kkeerrnneell). In OS

X 10.4.x, in-kernel was the default behavior for UDRW and

SPARSE images. On OS X 10.5, these and other kernel-compati-

ble images, including RAM-based images described in hdid(8),

will attach with a user process unless aattttaacchh --kkeerrnneell is used

or the corresponding variable is set. If an image is not

"kernel-compatible" and -kkeerrnneell is specified, the attach will

fail. (WARNING: ram:// images currently use wired memory when

attached in-kernel).

comapplediskimagesinsecureHTTP

disable SSL peer verification the same way -iinnsseeccuurreehhttttpp does.

Useful for clients of DiskImages such as asr(8) which don't support a similar command line option. EERRRROORRSS DiskImages uses many frameworks and can encounter many error codes. In general, it tries to turn these errors numbers into localized strings for the user. For background, intro(2) is a good explanation of the initial

error domain, the BSD errno values. For debugging, -vveerrbboossee should gen-

erally provide enough information to figure out what has gone wrong. The

following is a list of interesting errors that hdiutil may encounter:

[ENXIO] Device not configured. This error is returned by DiskImages when its kernel driver or framework helper cannot be contacted. The former usually means the IOHDIXController kernel extension can't be loaded. The latter usually means Foundation's distributed objects RPC mechanism cannot be configured. DO doesn't work under dead mach bootstrap contexts such as exist in a reattached screen(1) session. Root users can take advantage of StartupItemContext(8) (in

/usr/libexec) to access the startup item mach boot-

strap context. [EINVAL] Invalid argument. This error is used in many contexts

and is often a clue that hhddiiuuttiill's arguments are sub-

tly non-sensical (e.g. an invalid layout name passed

to ccrreeaattee -llaayyoouutt).

[EFBIG] File too large. DiskImages uses this error explicitly when attempting to access a disk image over HTTP that is too large for the server to support Range requests. See hdid(8) for more details. [EAUTH] Authentication error. Used by DiskImages when libcurl(3) is unable to verify its SSL peer. See

-iinnsseeccuurreehhttttpp for more information.

[EBUSY] Resource busy. Used if necessary exclusive access cannot be obtained. For example, returned by ccrreeaattee

-oovv when the image is attached.

EACCES vs. EPERM EACCES and EPERM are subtly different. The latter

"operation not permitted" tends to refer to an opera-

tion that cannot be performed, often due to an incor-

rect effective user ID. On the other hand, "permis-

sion denied" tends to mean that a particular access mode prevented the operation. UUSSIINNGG PPEERRSSIISSTTEENNTT SSPPAARRSSEE IIMMAAGGEESS As of OS X 10.5, a more reliable, efficient, and scalable sparse format, UDSB (SPARSEBUNDLE), is recommended for persistent sparse images as long as a backing bundle (directory) is acceptable. SPARSE (USSP) images and shadow files were designed for intermediate use when creating other images (e.g. UDZO) when final image sizes are unknown. As of OS X

10.3.2, partially-updated SPARSE images are properly handled and are thus

safe for persistent storage. SPARSE images are not recommended for per-

sistent storage on versions of OS X earlier than 10.3.2 and should gener-

ally only be used when data sizes are truly unknown. rreessiizzee can resize an HFS+ filesystem and the image containing it. If more space is needed than is referenced by the hosted filesystem,

ccrreeaattee -stretch and rreessiizzee can help to grow or shrink the filesystem in

the image. ccoommppaacctt reclaims unused space in the image. Beware that sparse images can enhance the effects of any fragmentation in the filesystem. To prevent errors when a filesystem inside of a sparse image has more free space than the volume holding the sparse image, HFS volumes inside sparse images will report an amount of free space slightly less than the amount of free space on the volume on which image resides. The image filesystem currently only behaves this way as a result of a direct aattttaacchh action and will not behave this way if, for example, the filesystem is unmounted and remounted (e.g. with uunnmmoouunntt and mmoouunnttvvooll). NNOOTTEE OONN DDEEVV EENNTTRRYY AACCCCEESSSS

Since any /dev entry can be treated as a raw disk image, it is worth not-

ing which devices can be accessed when and how. /dev/rdisk nodes are

character-special devices, but are "raw" in the BSD sense and force

block-aligned I/O. They are closer to the physical disk than the buffer

cache. /dev/disk nodes, on the other hand, are buffered block-special

devices and are used primarily by the kernel's filesystem code. It is not possible to read from a /dev/disk node while a filesystem is mounted from it, but anyone with read access to the appropriate /dev/rdisk node can use hhddiiuuttiill verbs such as ffssiidd on it. The DiskImages framework will attempt to use authopen(1) to open any device which it can't open (due to EACCES) for reading with open(2). This may cause apparent hangs while trying to access /dev entries while logged in remotely (an authorization panel is waiting on console). Generally, the /dev/disk node is preferred for imaging devices (e.g.

ccoonnvveerrtt or ccrreeaattee -ssrrccffoollddeerr operations), while /dev/rdisk is usable for

the quick ppmmaapp or ffssiidd. In particular, converting the blocks of a

mounted journaled filesystem to a read-only image will prevent the volume

in the image from mounting (the journal will be permanently dirty). CCOOMMPPAATTIIBBIILLIITTYY OS X 10.0 supported the disk images of Disk Copy 6 on Mac OS 9. OS X

10.1 added sparse, encrypted, and zlib-compressed images. These images

will not be recognized on OS X 10.0 (or will attach read/write, possibly allowing for their destruction). As the sparse, shadow, and encrypted formats have evolved, switches have been added to facilitate the creation of images that are compatible with older OS versions (at the expense of the performance and reliability improvements offered by the format enhancements). In particular, sparse images should not be expected to attach on versions of OS X older than that which created them.

With OS X 10.2, the most common image formats went "in-kernel" (i.e. the

DiskImages kernel extension served them without a helper process), image

meta-data began being stored both as XML and in the embedded resource

fork, and the default Disk Copy.app "compressed" format became UDZO

(breaking compatibility with 10.0). OS X 10.4 introduced bzip2 compres-

sion in the UDBZ format which provides smaller images (especially when combined with mmaakkeehhyybbrriidd) at the expense of backwards compatibility. In OS X 10.4.7, the resource forks previously embedded in UDIF images were abandoned entirely to avoid metadata length limitations imposed by resource fork structures. As a result, UDIF images created on 10.4.7 and later will not be recognized by either OS X 10.1 or OS X 10.0. ffllaatttteenn can be used to customize the type of metadata stored in the image. OS X 10.5 introduced sparse bundle images which ccoommppaacctt very efficiently. HISTORY

Disk images were first invented to electronically store and transmit rep-

resentations of floppy disks for manufacturing replication. These images

of floppies are typically referred to as 'Disk Copy 4.2' images, in ref-

erence to the application that created these images and restored them to floppy disks. Disk Copy 4.2 images were block for block representations of a floppy disk, with no notion of compression. DART is a variant of the Disk Copy 4.2 format that supported compression of the floppy image. NDIF (New Disk Image Format) images were developed to replace the Disk Copy 4.2 and DART image formats and to support images larger than a floppy disk. With NDIF and Disk Copy version 6, images could be

"attached" as mass storage devices under Mac OS 9. Apple Data Compres-

sion (ADC) - which carefully optimizes for fast decompression - was

used to compress images that were typically created once and restored many times during manufacturing. UDIF (Universal Disk Image Format) device images picked up where NDIF left off, allowing images to represent entire block devices and all the

data therein: DDM, Apple partition scheme partition map, disk-based driv-

ers, etc. For example, it can represent bootable CD's which can then be

replicated from an image. To be single-forked (vs. the dual-fork NDIF),

it began storing its metadata in an embedded resource. UDIF is the native image format for OS X. Raw disk images from other operating systems (e.g. .iso files) will be

recognized as disk images and can be attached and mounted if OS X recog-

nizes the filesystems. They can also be burned with hhddiiuuttiill bbuurrnn. WWHHAATT''SS NNEEWW In OS X 10.3, most Disk Copy functionality moved to Disk Utility and a new background application DiskImageMounter handles attaching images. As of OS X 10.4, encrypted images (such as those used for FileVault) can be attached without a helper process and "image from folder" operations

no longer require more disk space than the final image. Images contain-

ing exotic-to-CD filesystems (such as MS-DOS) can have their files burned

with bbuurrnn -ssyynntthheessiizzee. Significant hhddiiuuttiill changes in 10.4 include the

addition of -ppuuppppeettssttrriinnggss to many verbs, -aannyyddeevviiccee becoming the default

for bbuurrnn, and signal handlers so that hdiutil can try to clean up before

quitting when canceled. And in OS X 10.4.7, all read-only UDIFs (includ-

ing the compressed types) began being handled by a helper process to free up resources in the kernel.