Mac Os x Manual Page - Hdiutil

8/6/2019 Mac Os x Manual Page - Hdiutil

1/19

This manual page is for Mac OS X version 10.6.6

Choose a version: 10.6.6

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

For more information about this technology, look for other documentation in the Apple Reference Library.

For general information about writing shell scripts, read Shell Scripting Primer.

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

NAMENAME

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

SYNOPSISSYNOPSIS

hdiutilhdiutil verb [options]

DESCRIPTIONDESCRIPTION

hdiutilhdiutil uses the DiskImages framework to manipulate disk images. Common verbs include attachattach, detachdetach,

verifyverify, createcreate, convertconvert, compactcompact, and burnburn.

The rest of the verbs are currently: helphelp, infoinfo, checksumchecksum, chpasschpass, unflattenunflatten, flattenflatten, imageinfoimageinfo,

isencryptedisencrypted, mountvolmountvol, unmount,unmount, pluginsplugins, udifrezudifrez, udifderezudifderez, internet-enableinternet-enable, resizeresize, segmentsegment,

makehybridmakehybrid, and pmappmap.

BACKGROUNDBACKGROUND

Disk images are containers that emulate disks. Like disks, they can be partitioned and formatted.

Many uses of disk images blur the distinction between the disk image container and its content, but

this distinction is critical to understanding disk images. The terms "attach" and "detach" are used to

distinguish the way disk images are connected to and disconnected from the system.

For example, when you double-click a disk image in the Mac OS X Finder, two separate things happen.

First, the image is "attached" to the system just like an external drive. Then, the kernel and Disk

Arbitration probe the new device for recognized file structures. If any file structures are under-

stood, the associated volumes will mount and appear in the Finder.

Always consider whether a "disk image" operation applies to the blocks of the disk image device or to

the (often file-oriented) content of the image. For example, verifyverify verifies that the blocks stored in

a read-only disk image have not changed since it was created. On the other hand, createcreate -srcfolder-srcfolder

creates a disk image container, puts a filesystem in it, and then copies the specified files to the new

filesystem.

COMMONCOMMON OPTIONSOPTIONS

The following option descriptions apply to all verbs:

-verbose-verbose be verbose: produce extra progress output and error diagnostics. This option can help the

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

images will be detailed.

-quiet-quiet close stdout and stderr, leaving only hdiutilhdiutil's exit status to indicate success or failure.

-debug-debug and -verbose-verbose disable -quiet-quiet.

-debug-debug be very verbose. This option is good if a large amount of progress information is needed. As

of Mac OS X 10.6, -debug-debug enables -verbose-verbose.

Many hdiutilhdiutil verbs understand the following options:

-plist-plist provide result output in plist format. Other programs invoking hdiutilhdiutil are expected to

use -plist-plist rather than try to parse the human-readable output. The usual output is

consistent but generally unstructured.


2/19

-puppetstrings-puppetstrings provide progress output that is easy for another program to parse. PERCENTAGE outputs

can include the value -1 which means hdiutilhdiutil is performing an operation that will take

an indeterminate amount of time to complete. Any program trying to interpret hdiutilhdiutil's

progress should use -puppetstrings-puppetstrings.

-srcimagekey-srcimagekey key=value

specify a key/value pair for the disk image recognition system. (-imagekey-imagekey is normally

a synonym)

-tgtimagekey-tgtimagekey key=value

specify a key/value pair for any image created. (-imagekey-imagekey is only a synonym if there

is no input image).

-encryption-encryption [AES-128|AES-256]

specify a particular type of encryption or, if not specified, the default encryption

algorithm. The default algorithm is the AES cipher with a 128-bit key.

-stdinpass-stdinpass read a null-terminated passphrase from standard input. If the standard input is a tty,

the passphrase will be read with readpassphrase(3). -stdinpass-stdinpass replaces -passphrase-passphrase

though the latter is still supported for compatibility. Beware that the password will

contain any newlines before the NULL. See EXAMPLES.

-agentpass-agentpass force the default behavior of prompting for a passphrase. Useful with -pubkey-pubkey to cre-

ate an image protected by both a passphrase and a public key.

-recover-recover keychain_filespecify a keychain containing the secret corresponding to the certificate specified

with -certificate-certificate when the image was created.

-certificate-certificate cert_file

specify a secondary access certificate for an encrypted image. cert_file must be DER-

encoded certificate data, which can be created by Keychain Access or openssl(1).

-pubkey-pubkey PK1,PK2,...,PKn

specify a list of public keys, identified by their hexadecimal hashes, to be used to

protect the encrypted image being created.

-cacert-cacert cert specify a certificate authority certificate. cert can be either a PEM file or a direc-

tory of certificates processed by c_rehash(1). See also --capath--capath and --cacert--cacert in

curl(1).

-insecurehttp-insecurehttp 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.

-shadow-shadow [shadowfile]

Use a shadow file in conjunction with the data in the primary image file. 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 an attached device will be

redirected to the shadow file. If not specified, shadowfile defaults to image.shadow.

If the shadow file does not exist, it is created. hdiutilhdiutil verbs taking images as input

accept -shadow-shadow, -cacert-cacert, and -insecurehttp-insecurehttp.

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 file-

name and changes its behavior accordingly. For example, a sparse image can be created without specify-

ing -type SPARSEBUNDLE simply by appending the .sparsebundle extension to the provided filename.

VERBSVERBS

Each verb is listed with its description and individual arguments. Arguments to the verbs can be

passed in any order. A sector is 512 bytes.

helphelp display minimal usage information for each verb. hdiutilhdiutil verb -help-help will provide basic

usage information for that verb.


3/19

attachattach image [options]

attach a disk image as a device. attachattach will return information about an already-attached

image as if it had attached it. mountmount is a poorly-named synonym for attachattach. See BACK-

GROUND.

Beware that an image freshly created and attached is treated as a new removable device. See

hdid(8) and the EXAMPLES section below for more details about how owners are ignored on

filesystems on such devices.

The output of attachattach has been stable since OS X 10.0 (though it was called hdid(8) then) and

is intended to be program-readable. It consists of the /dev node, a tab, a content hint (if

applicable), another tab, and a mount point (if any filesystems were mounted). Because con-

tent hints are derived from the partition data, GUID Partition Table types may leak through.Common GUIDs such as "48465300-0000-11AA-AA11-0030654" are mapped to their human-readable

counterparts (here "Apple_HFS").

Common options: -encryption-encryption, -stdinpass-stdinpass, -recover-recover, -imagekey-imagekey, -shadow-shadow, -puppetstrings-puppetstrings, a

-plist-plist.

Options:

-readonly-readonly force the resulting device to be read-only

-readwrite-readwrite attempt to override the DiskImages framework's decision to attach a par-

ticular image read-only. For example, -readwrite-readwrite can be used to modify

the HFS filesystem on a HFS/ISO hybrid CD image.

-nokernel-nokernel attach with a helper process. This is again the default as of OS X 10.5.

-kernel-kernel attempt to attach this image without a helper process; fail if unsup-

ported. Only UDRW, UDRO, UDZO, and UDSP images are supported in-kernel.Encryption and HTTP-backed images are also supported.

-notremovable-notremovable prevent this image from being detached. Only root can use this option.

-mount-mount required|optional|suppressed

indicate whether filesystems in the image should be mounted or not. The

default is required (attachattach will fail if no filesystems mount).

-nomount-nomount identical to -mount-mount suppressed.

-mountroot-mountroot path mount volumes on subdirectories of path instead of under /Volumes. path

must exist. Full mount point paths must be less than MNAMELEN characters

(increased from 90 to 1024 in OS X 10.6).

-mountrandom-mountrandom path like -mountroot-mountroot, but mount point directory names are randomized with

mkdtemp(3).

-mountpoint-mountpoint path assuming only one volume, mount it at path instead of in /Volumes. Seefstab(5) for ways a system administrator can make particular volumes

automatically mount in particular filesystem locations by editing the

file /etc/fstab.

-union-union attempt a union mount over the mount point specified by -mountpoint-mountpoint.

Union mounts are no longer supported in Mac OS X, so this flag is cur-

rently a no-op.

-private-private suppress filesystem mount notifications. -private-private confuses programs

using the Carbon File Manager and should be avoided in favor of

-nobrowse-nobrowse.

-nobrowse-nobrowse render any volumes invisible in applications such as the OS X Finder.

-owners-owners on|off specify that owners on any filesystems be honored or not.

-drivekey-drivekey key=value

specify a key/value pair to be attached to the device in the IOKit reg-

istry.

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 to over-

ride any existing preferences.

-[no]verify-[no]verify do [not] verify the image. By default, hdiutilhdiutil attachattach attempts to intel-

ligently verify images that contain checksums before attaching them. If

hdiutilhdiutil can write to an image it has verified, attachattach will store an

attribute with the image so that it will not be verified again unless its

timestamp changes. To maintain backwards compatibility, hdid(8) does not

attempt to verify images before attaching them.

Preferences keys: skip-verify, skip-verify-remote, skip-verify-locked,

- -


4/19

-[no]ignorebadchecksums-[no]ignorebadchecksums

specify whether bad checksums should be ignored. The default is to abort

when a bad checksum is detected.

Preferences key: ignore-bad-checksums

-[no]idme-[no]idme do [not] perform IDME actions on IDME images. IDME actions are normally

only performed when Safari downloads and attaches an image.

Preferences key: skip-idme

-[no]idmereveal-[no]idmereveal do [not] reveal (in the Finder) the results of IDME processing.

Preferences key: skip-idme-reveal

-[no]idmetrash-[no]idmetrash do [not] put IDME images in the trash after processing.

Preferences key: skip-idme-trash

-[no]autoopen-[no]autoopen do [not] auto-open volumes (in the Finder) after attaching an image. Bydefault, read-only volumes are opened in the Finder.

-[no]autoopenro-[no]autoopenro do [not] auto-open read-only volumes.

Preferences key: auto-open-ro-root

-[no]autoopenrw-[no]autoopenrw do [not] auto-open read/write volumes.

Preferences key: auto-open-rw-root

-[no]autofsck-[no]autofsck do [not] force automatic file system checking before mounting a disk

image. By default, only quarantined images (e.g. downloaded from the

Internet) that have not previously passed fsck are checked.

Preferences key: auto-fsck

detachdetach dev_name [-force-force]

detach a disk image and terminate any associated process. dev_name is a partial /dev node

path (e.g. "disk1"). As of OS X 10.4, dev_name can also be a mountpoint. If Disk Arbitra-

tion is running, detachdetach will use it to unmount any filesystems and detach the image. Ifnot, detachdetach 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. ejecteject is a synonym for detachdetach.

Options:

-force-force ignore open files on mounted volumes, etc.

verifyverify image [options]

compute the checksum of a "read-only" or "compressed" image and verify it against the value

stored in the image. Read/write images don't contain checksums and thus can't be verified.

verifyverify accepts the common options -encryption-encryption, -stdinpass-stdinpass, -srcimagekey-srcimagekey, -puppetstrings-puppetstrings,

-plist-plist.

createcreate size_spec imagecreate a new image of the given size or from the provided data. If image already exists,

-ov-ov must be specified or createcreate will fail. To make a cross-platform CD or DVD, use

makehybridmakehybrid instead. See also EXAMPLES below.

The size specified is the size of the image to be created. Filesystem and partition layout

overhead (80 sectors for the default GPTSPUD layout on Intel machines) may not be available

for the filesystem and user data in the image.

Size specifiers:

-size-size ??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 useful for large sparse images.

-sectors-sectors sector_count

Specify the size of the image file in 512-byte sectors.-megabytes-megabytes size

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

-srcfolder-srcfolder source

copies file-by-file the contents of source into image, creating a fresh (theoret-

ically defragmented) filesystem on the destination. The resulting image is thus

recommended for use with asr(8)since it will have a minimal amount of unused

space. Its size will be that of the source data plus some padding for filesystem

overhead. The filesystem type of the image volume will match that of the source

as closely as possible unless overridden with -fs-fs. Other size specifiers, such

as -size-size, will override the default size calculation based on the source content,

allowing for more or less free space in the resulting filesystem. -srcfolder-srcfolder can


5/19

e spec e more an once, n w c case e mage vo ume w e popu a e a

the top level with a copy of each specified filesystem object. -srcdir-srcdir is a syn-

onym.

-srcdevice-srcdevice device

specifies that the blocks of device should be used to create a new image. The

image size will match the size of device. resizeresize can be used to adjust the size

of resizable filesystems and writable images. Both -srcdevice-srcdevice and -srcfolder-srcfolder 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. Data will be lost, but the image creation operation will subse-

quently succeed. Filesystem options (like -fs-fs, -volname-volname, -stretch-stretch, or -size-size) are

invalid and ignored when using -srcdevice-srcdevice.

Common options: -encryption-encryption, -stdinpass-stdinpass, -certificate-certificate, -pubkey-pubkey, -plist-plist, -imagekey-imagekey,

-tgtimagekey-tgtimagekey, -puppetstrings-puppetstrings, and -plist-plist.

-imagekey-imagekey di-sparse-puma-compatible=TRUE and -imagekey-imagekey di-shadow-puma-compatible=TRUE will

create, respectively, sparse and shadow images that can be attached on OS X 10.1. -imagekey-imagekey

encrypted-encoding-version can select between version 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 and as of OS X 10.5, all encrypted images default to

version 2.

General options:

-align-align alignment

specifies a size to which the final data partition will be aligned. The default

is 4K.

-type-type UDIF|SPARSE|SPARSEBUNDLE

-type-type is particular to createcreate and is used to specify the format of empty

read/write images. It is independent of -format-format which is used to specify the

final read-only image format when populating an image with pre-existing content.

UDIF is the default type. If specified, a UDRW of the specified size will be cre-

ated. 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 image backed by a

directory bundle.

By default, UDSP images grow one megabyte at a time. Introduced in 10.5, UDSB

images use 8 MB band files which grow as they are written to.. -imagekey-imagekey

sparse-band-size=size can be used to specify the number of 512-byte sectors that

will be added each time the image grows. Valid values for SPARSEBUNDLE range from

2048 to 262144 sectors (1 MB to 128 MB).

The maximum size of a SPARSE image is 128 petabytes; the maximum for SPARSEBUNDLE

is just under 8 exabytes (2^63 - 512 bytes minus 1 byte). The amount of data that

can be stored in either type of sparse image is additionally bounded by the

filesystem in the image and by any partition map. compactcompact can reclaim unused

bands in sparse images backing HFS+ filesystems. resizeresize will only change the vir-

tual size of a sparse image. See also USING PERSISTENT SPARSE IMAGES below.

-fs-fs filesystemwhere filesystem is one of HFS+, HFS+J (JHFS+), HFSX, JHFS+X, MS-DOS, or UDF. -fs-fs

causes a filesystem of the specified type to be written to the image. -fs-fs may

change the partition scheme and type appropriately. -fs-fs will not make any size

adjustments: if the image is the wrong size for the specified filesystem, createcreate

will fail. -fs-fs is invalid and ignored when using -srcdevice-srcdevice.

-volname-volname volname

The newly-created filesystem will be named volname. The default depends the

filesystem being used; HFS+'s default volume name is ùntitled'. -volname-volname is

invalid and ignored when using -srcdevice-srcdevice.

-uid-uid uid the root of the newly-created volume will be owned by the given numeric user id.

99 maps to the magic ùnknown' user (see hdid(8)).

-gid-gid gid the root of the newly-created volume will be owned by the given numeric group id.

99 ma s to ùnknown'.


6/19

-mode-mode mode the root of the newly-created volume will have mode (in octal) mode. The default

mode is determined by the filesystem's newfs unless -srcfolder-srcfolder is specified, in

which case the default mode is derived from the specified filesystem object.

-[no]autostretch-[no]autostretch

do [not] suppress automatically making backwards-compatible stretchable volumes

when the volume size crosses the auto-stretch-size threshold (default: 256 MB).

See also asr(8).

-stretch-stretch max_stretch

-stretch-stretch initializes HFS+ filesystem data such that it can later be stretched on

older systems (which could only stretch within predefined limits) using hdiutilhdiutil

resizeresize or by asr(8). max_stretch is specified like -size-size. -stretch-stretch is invalid

and ignored when using -srcdevice-srcdevice.-fsargs-fsargs newfs_args

additional arguments to pass to whatever newfs program is implied by -fs-fs.

newfs_hfs(8) has a number of options that can reduce the amount of space needed by

the filesystem's data structures. Suppressing the journal with -fs-fs HFS+ and pass-

ing arguments such as -c c=64,a=16,e=16 to -fsargs-fsargs will minimize gaps at the front

of the filesystem, allowing resizeresize to squeeze more space from the filesystem. For

truly optimal filesystems, use makehybridmakehybrid.

-layout-layout layout

Specify the partition layout of the image. layout can be anything supported by

MediaKit.framework. NONE creates an image with no partition map. When such an

image is attached, a single /dev entry will be created (e.g. /dev/disk1).

`SPUD' causes a DDM and an Apple Partition Scheme partition map with a singleentry to be written. `GPTSPUD' creates a similar image but with a GUID Partition

Scheme map instead. When attached, multiple /dev entries will be created, with

either slice 1 (GPT) or slice 2 (APM) as the data partition. (e.g. /dev/disk1,

/dev/disk1s1, /dev/disk1s2).

Unless overridden by -fs-fs, the default layout is `GPTSPUD' (PPC systems used `SPUD'

prior to OS X 10.6). Other layouts include `MBRSPUD' and `ISOCD'. createcreate -help-help

lists all supported layouts.

-library-library bundle

specify an alternate layout library. The default is MediaKit's MKDrivers.bundle.

-partitionType-partitionType partition_type

Change the type of partition in a single-partition disk image. The default is

Apple_HFS unless -fs-fs implies otherwise.

-ov-ov overwrite an existing file. The default is not to overwrite existing files.

-attach-attach attach the image after creating it. If no filesystem is specified via -fs-fs, the

attach will fail per the default attachattach -mount-mount required behavior.

Image from source options (for -srcfolder-srcfolder and -srcdevice-srcdevice):

-format-format 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 convertconvert.

Options specific to -srcdevice-srcdevice:

-segmentSize-segmentSize size_spec

Specify that the image should be written in segments no bigger than size_spec

(which follows -size-size conventions).

Options specific to -srcfolder-srcfolder:-[no]crossdev-[no]crossdev do [not] cross device boundaries on the source filesystem.

-[no]scrub-[no]scrub do [not] skip temporary files when imaging a volume. Scrubbing is the

default when the source is the root of a mounted volume. Scrubbed items

include trashes, temporary directories, swap files, etc.

-[no]anyowners-[no]anyowners do not fail if the user invoking hdiutilhdiutil can't ensure correct file ownership

for the files in the image.

-skipunreadable-skipunreadable skip files that can't be read by the copying user and don't authenticate.

-copyuid-copyuid user perform the copy as the given user. Requires root privilege. If user can't

read or create files with the needed owners, -anyowners-anyowners or -skipunreadable-skipunreadable

must be used to prevent the operation from failing.

By default, createcreate -srcfolder-srcfolder attempts to maintain the permissions present in the source


7/19

directory. It prompts for authentication 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.

convertconvert image -format-format format -o-o outfile

convert image to type format and write the result to outfile.

As with createcreate, 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 imageUDZO - 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

skip unused space in HFS, UFS, and MS-DOS (FAT) filesystems. For UDZO, -imagekey-imagekey

zlib-level=value allows the zlib compression level to be specified ala gzip(1). The default

compression level is 1 (fastest).

Common options: -encryption-encryption, -stdinpass-stdinpass, -certificate-certificate, -srcimagekey-srcimagekey, -tgtimagekey-tgtimagekey, -shad-shad

and related, -puppetstrings-puppetstrings, and -plist-plist.

Other options:

-align-align alignment

The default is 4 (2K).

-pmap-pmap add partition map.

When converting a NDIF to a any variety of UDIF, or when converting an unparti-

tioned UDIF, the default is true.

-segmentSize-segmentSize [size_spec]

Specify segmentation into size_spec-sized segments as outfile is being written.

The default size_spec when -segmentSize-segmentSize 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. size_spec can also be specified ??b|??k|??m|??g|??t??p|??e like

createcreate's -size-size flag.

-tasks-tasks task_count

When converting an image into a compressed format, specify the number of

threads to use for the compression operation. The default is the number of

processors active in the current system.

burnburn image

Burn image to optical media in an attached burning device. In all cases, a prompt for media

will be printed once an appropriate drive has been found. Common options: -shadow-shadow and

related, -srcimagekey-srcimagekey, -encryption-encryption, -puppetstrings-puppetstrings, and -stdinpass-stdinpass.

Other options:

-device-device specify a device to use for burning. See -list-list.

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

-anydevice-anydevice explicitly allow burning to devices not qualified by Apple (kept for back-

wards compatibility as burnburn will burn to any device by default as of OS X

10.4).

-[no]eject-[no]eject do [not] eject disc after burning. The default is to eject the disc.

--


8/19

. .

-[no]addpmap-[no]addpmap 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 par-

tition map. This option will add a partition map to any bare filesystem

which needs a partition map in order to be recognized when burned to opti-

cal media. The default is to add the partition map if needed.

-[no]skipfinalfree-[no]skipfinalfree do [not] skip final free partition. If there is a partition map on the

image specifying an Apple_Free partition as the last partition, that

Apple_Free 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.

-[no]optimizeimage-[no]optimizeimage 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 vol-

ume. This option will change what is burned such that the disc will have a

different checksum than the image it came from. The default is to burn all

blocks of the disk image (minus any trailing Apple_Free).

-[no]forceclose-[no]forceclose 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.

-nounderrun-nounderrun Disable the default buffer underrun protection.

-[no]synthesize-[no]synthesize [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 notbe legally burned to a disc.

-speed-speed x_factor 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. -speed-speed 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.

-sizequery-sizequery calculate the size of disc required (the size returned is in sectors) with-

out burning anything.

-erase-erase 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.

-fullerase-fullerase erase all sectors of the disc (this usually takes quit a bit longer than

-erase-erase).

-list-list list all burning devices, with OpenFirmware paths suitable for -device-device.

makehybridmakehybrid -o-o image source

Generate a potentially-hybrid filesystem in a read-only disk image using the DiscRecording

framework's content creation system. This disk image will represent a data disc. drutil(1)

can be used to make audio discs.

source can either be a directory or a disk image. The generated image can later be burned

using burnburn, or converted to another read-only format with convertconvert. By default, the filesys-tem will be readable on most modern computing platforms. The generated filesystem is not

intended for conversion 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).

hdiutilhdiutil 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 partitioned hard disk, respectively. The El Torito options should not be

used for data CDs.


9/19

esystem opt ons:

-hfs-hfs Generate an HFS+ filesystem. This filesystem can be present on an image simultane-

ously with an ISO9660 or Joliet or UDF filesystem. On operating systems that under-

stand HFS+ as well as ISO9660 and UDF, like Mac OS 9 or Mac OS X, it is usually the

preferred filesystem.

-iso-iso 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 filesys-

tem is present on a disk image or CD, but not HFS+, Mac OS X will use the ISO9660

(or Joliet) filesystem.

-joliet-joliet Generate Joliet extensions to ISO9660. This view of the filesystem can be present

on an image simultaneously with HFS+, and requires the presence of an ISO9660filesystem. Joliet supports Unicode filenames, but is only supported on some oper-

ating systems. 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.

-udf-udf 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 filesys-

tems as a hybrid image. When multiple filesystems are selected, the data area of the image

is shared between all filesystems, and only directory information 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):-hfs-blessed-directory-hfs-blessed-directory Path to directory which should be "blessed" for Mac OS X booting on

the generated filesystem. This assumes the directory has been other-

wise prepared, for example with bless -bootinfo-bootinfo to create a valid

BootX file. (HFS+ only).

-hfs-openfolder-hfs-openfolder Path to a directory that will be opened by the Finder automatically.

See also the -openfolder-openfolder option in bless(8) (HFS+ only).

-hfs-startupfile-size-hfs-startupfile-size Allocate an empty HFS+ Startup File of the specified size, in bytes

(HFS+ only).

-abstract-file-abstract-file Path to a file in the source directory (and thus the root of the gen-

erated filesystem) for use as the ISO9660/Joliet Abstract file

(ISO9660/Joliet).

-bibliography-file-bibliography-file Path to a file in the source directory (and thus the root of the gen-

erated filesystem) for use as the ISO9660/Joliet Bibliography file

(ISO9660/Joliet).

-copyright-file-copyright-file Path to a file in the source directory (and thus the root of the gen-

erated filesystem) for use as the ISO9660/Joliet Copyright file

(ISO9660/Joliet).

-application-application Application string (ISO9660/Joliet).

-preparer-preparer Preparer string (ISO9660/Joliet).

-publisher-publisher Publisher string (ISO9660/Joliet).

-system-id-system-id System Identification string (ISO9660/Joliet).

-keep-mac-specific-keep-mac-specific Expose Macintosh-specific files (such as .DS_Store) in non-HFS+

filesystems (ISO9660/Joliet).

-eltorito-boot-eltorito-boot Path to an El Torito boot image within the source directory. 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-no-emul-boot-no-emul-boot or -hard-disk-boot-hard-disk-boot must be used to enable "No

Emulation" or "Hard Disk Emulation" mode, respectively

(ISO9660/Joliet).

-hard-disk-boot-hard-disk-boot Use El Torito Hard Disk Emulation mode. The image must represent a

virtual device with an MBR partition map and a single partition

-no-emul-boot-no-emul-boot Use El Torito No Emulation mode. The system firmware will load the

number of sectors specified by -boot-load-size-boot-load-size and execute it, with-

out emulating any devices (ISO9660/Joliet).

-no-boot-no-boot 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).

-boot-load-seg-boot-load-seg For a No Emulation boot image, load the data at the specified segment

address. This o tions is not recommended so that the s stem


10/19

firmware can use its default address (ISO9660/Joliet)

-boot-load-size-boot-load-size 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).

-eltorito-platform-eltorito-platform Use the specified numeric platform ID in the El Torito Boot Catalog

Validation Entry or Section Header. Defaults to 0 to identify x86

hardware (ISO/Joliet).

-eltorito-specification-eltorito-specification For complex layouts involving multiple boot images, a plist-format-

ted string can be provided, using either OpenStep-style syntax or XML

syntax, representing 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 -eltorito-specification-eltorito-specification is provided in addition

to the normal El Torito command-line options, the specification will

be used to populate secondary non-default boot entries.

-udf-version-udf-version Version of UDF filesystem to generate. This can be either "1.02" or

"1.50". If not specified, it defaults to "1.50" (UDF).

-default-volume-name-default-volume-name Default volume name for all filesystems, unless overridden. If not

specified, defaults to the last path component of source.

-hfs-volume-name-hfs-volume-name Volume name for just the HFS+ filesystem if it should be different

(HFS+ only).

-iso-volume-name-iso-volume-name Volume name for just the ISO9660 filesystem if it should be different

(ISO9660 only).

-joliet-volume-name-joliet-volume-name Volume name for just the Joliet filesystem if it should be different

(Joliet only).

-udf-volume-name-udf-volume-name Volume name for just the UDF filesystem if it should be different(UDF only).

-hide-all-hide-all A glob expression of files and directories that should not be exposed

in the generated filesystems. The string may need to be quoted to

avoid shell expansion, and will be passed to glob(3) for evaluation.

Although this option cannot be used multiple times, an arbitrarily

complex glob expression can be used.

-hide-hfs-hide-hfs A glob expression of files and directories that should not be exposed

via the HFS+ filesystem, although the data may still be present for

use by other filesystems (HFS+ only).

-hide-iso-hide-iso A glob expression of files and directories 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 hier-

archy will supersede the ISO hierarchy when the hybrid is mounted asan ISO 9660 filesystem on Mac OS X. Therefore, if Joliet is being

generated (the default) -hide-joliet-hide-joliet will also be needed to hide the

file from mount_cd9660(8).

-hide-joliet-hide-joliet A glob expression of files and directories 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, -hide-joliet-hide-joliet

effectively supersedes -hide-iso-hide-iso when the resulting filesystem is

mounted as ISO on OS X.

-hide-udf-hide-udf A glob expression of files and directories that should not be exposed

via the UDF filesystem, although the data may still be present for

use by other filesystems (UDF only).

-only-udf-only-udf A glob expression of objects that should only be exposed in UDF.

-only-iso-only-iso A glob expression of objects that should only be exposed in ISO.-only-joliet-only-joliet A glob expression of objects that should only be exposed in Joliet.

-print-size-print-size 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.

-plistin-plistin Instead of using command-line parameters, use a standard plist from

standard input to specific the parameters of the hybrid image genera-

tion. 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".


11/19

If a disk image was specified for source, the image will be attached and paths will be eval-

uated relative to the mountpoint 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 drutildrutil filenamefilename myname to see how a given string would be remapped.

The -abstract-file-abstract-file, -bibliography-file-bibliography-file, -and-and -copyright-file-copyright-file must exist directly in the

source directory, not a sub-directory, and must have an 8.3 name for compatibility with

ISO9660 Level 1.

compactcompact image

scans the bands of a sparse (SPARSE or SPARSEBUNDLE) disk image containing an HFS filesys-

tem, 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, compactcompact may or may not shrink

the image. For SPARSEBUNDLE images, completely unused band files are simply removed.

Common options: -encryption-encryption, -stdinpass-stdinpass, -srcimagekey-srcimagekey, -shadow-shadow and related, -puppetstring-puppetstring

and -plist-plist.

infoinfo display information about DiskImages.framework, the disk image driver, and any images that

are currently attached. hdiutilhdiutil infoinfo accepts -plist-plist.

checksumchecksum image -type-type type

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

Common options: -shadow-shadow and related, -encryption-encryption, -stdinpass-stdinpass. -srcimagekey-srcimagekey, -puppetstrin-puppetstrin

and -plist-plist,

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

chpasschpass image

change the passphrase for an encrypted image. The default is to change the password inter-

actively.

Common options: -recover-recover and -srcimagekey-srcimagekey. The options -oldstdinpass-oldstdinpass and -newstdinpass-newstdinpass

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 -stdinpass-stdinpass.

unflattenunflatten image

unflatten a UDIF disk image, creating an OS 9-style dual-fork image file (no XML metadata).

If the resource fork representation of the metadata becomes greater than 16 MB, the opera-

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

Common options: -encryption-encryption, -stdinpass-stdinpass, and -srcimagekey-srcimagekey.

flattenflatten 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).

Common options: -srcimagekey-srcimagekey, -encryption-encryption, and -stdinpass-stdinpass. Since images are created "flat"

b default, flattenflatten is onl re uired if the UDIF has reviousl been unflattenunflattened.


12/19

Other options:

-noxml-noxml don't embed XML data for in-kernel attachment. The image will never attach in-

kernel.

-norsrcfork-norsrcfork don't embed resource fork data. The image will not attach on OS X versions

prior to OS X 10.2.

fsidfsid image

Print information about file systems on a given disk image. As usual, image can be a /dev

entry corresponding to a physical disk. See the NOTE ON DEV ENTRY ACCESS section. More

detailed information is presented for HFS file systems.

Common options: -encryption-encryption, -stdinpass-stdinpass, -srcimagekey-srcimagekey, and -shadow-shadow and related.

mountvolmountvol dev_name

mount the filesystem in dev_name using Disk Arbitration (similar to diskutil(8)'s mountmount).

XML output is available from -plist-plist. Note that mountvolmountvol (rather than mountmount, 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 unmountunmount.

Prior to OS X 10.5, mountmount/attachattach would treat a /dev entry as a disk image to be attached

(creating another /dev entry). That behavior was undesirable.

unmountunmount volume [-force-force]

unmount a mounted volume without detaching any associated image. Volume is a /dev entry or

mountpoint. NOTE: unmountunmount does NOT detach any disk image associated with the volume.Images are attached and detached; volumes are mounted and unmounted. mountvolmountvol will remount

a volume that has been unmounted by unmountunmount.

Options:

-force-force unmount filesystem regardless of open files on that filesystem. Similar to umount

-f.

imageinfoimageinfo image

Print out information about a disk image.

Common options: -encryption-encryption, -stdinpass-stdinpass, -srcimagekey-srcimagekey, -shadow-shadow and related, and -plist-plist.

Options are any of:

-format-format just print out the image format-checksum-checksum just print out the image checksum

isencryptedisencrypted image

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

printed.

Common options: -plist-plist.

pluginsplugins 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: -plist-plist.

internet-enableinternet-enable [-yes-yes] | -no-no | -query-query image

Enable or disable download post-processing (IDME). -yes-yes is the default. When enabled, a

browser (or Disk Copy 10.2.3+) will "unpack" the contents: the image's visible contents will

be copied into the directory containing the image and the image will be put into the trash

with IDME disabled.

Common options: -encryption-encryption, -stdinpass-stdinpass, -srcimagekey-srcimagekey, and -plist-plist.

resizeresize size_spec image

Resize a disk image or the containers within it. For an image containing a trailing

Apple_HFS partition, the default behavior is to resize the image container, the partition,


13/19

and the filesystem within it by aligning the end of the latter with the end of the image.

On older systems, resizeresize was limited to pre-defined limits that depended on how the filesys-

tem was created. As of OS X 10.4, resizeresize can be used to grow an HFS filesystem within an

image to any size supported by HFS and the filesystem hosting the image.

resizeresize 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 resizeresize does not move data. diskutil(8) resizeresize can be used to move filesystem

data so that hdiutilhdiutil resizeresize can make an image barely larger than the data within it.

-fsargs-fsargs can sometimes be used to minimize filesystem gaps in the image contents. resizeresize 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+).

hdiutilhdiutil burnburn does not burn Apple_Free 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: -encryption-encryption, -stdinpass-stdinpass, -srcimagekey-srcimagekey, -shadow-shadow and related, and -plist-plist.

Size specifiers:

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

-sectors-sectors sector_count | min

Specify the number of 512-byte sectors to which the partition should be

resized. If this falls outside the mininum valid value or space remaining

on the underlying file system, an error will be returned and the partition

will not be resized. min automatically determines the smallest possible

size.

Other options:

-imageonly-imageonly only resize the image file, not the partition(s) and filesystems inside of

it.

-partitiononly-partitiononly only resize a partition / filesystem in the image, not the image.

-partitiononly-partitiononly will fail if the new size won't fit inside the image. On

APM, shrinking a partition results in an explicit Apple_Free entry taking

up the remaining space in the image.

-partitionNumber-partitionNumber partitionNumber

specifies which partition to resize (UDIF only -- see HISTORY below).

partitionNumber is 0-based, but, per hdiutilhdiutil pmappmap, partition 0 is the par-

tition map itself.

-growonly-growonly only allow the image to grow-shrinkonly-shrinkonly only allow the image to shrink

-nofinalgap-nofinalgap allow resize to entirely eliminate the trailing free partition in an APM

map. Restoring such images to very old hardware may interfere with boot-

ing.

-limits-limits Displays the minimum, current, and maximum sizes (in 512-byte sectors) for

the image. In addition to any hosted filesystem constraints, UDRW images

are constrained by available disk space in the filesystem hosting the

image. -limits-limits does not modify the image.

segmentsegment

segmentsegment -o-o firstSegname -segmentCount-segmentCount #segs image [opts]

segmentsegment -o-o firstSegname -segmentSize-segmentSize 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 segmentsegment and not by the

state of the source image.

Common options: -encryption-encryption, -stdinpass-stdinpass, -srcimagekey-srcimagekey, -tgtimagekey-tgtimagekey, -puppetstrings-puppetstrings, and

-plist-plist.

Options:

-segmentCount-segmentCount segment_count

Specify the number of segments. Only one of -segmentCount-segmentCount or -segmentSize-segmentSize will

be honored.

--


14/19

_

Specify the segment size in sectors or in the style of mkfile(8) (here unquali-

fied 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 -segmentCount-segmentCount or -segmentSize-segmentSize will be honored. Segmenting

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

-firstSegmentSize-firstSegmentSize segment_size

Specify the first segment size in sectors in the same form as for -segmentSize-segmentSize.

Used for multi-CD restores.

-restricted-restricted Make restricted segments for use in multi-CD restores.

-ov-ov overwrite any existing files.

pmappmap [options image]

display the partition map of an image or device. By default, this report includes offsets

and significant amounts of free space. image is either a plain or special file (i.e. a

/dev/disk entry). See the NOTE ON DEV ENTRY ACCESS below.

Common options: -encryption-encryption, -stdinpass-stdinpass, -srcimagekey-srcimagekey, and -shadow-shadow and related.

-simple-simple generate MediaKit's minimal report: partition types, names, and sizes in

human-readable units.

-standard-standard generate MediaKit's standard report, which adds partition offsets and uses

512-byte sectors.

-complete-complete generate MediaKit's comprehensive report, with end offsets, significant free

space, etc.

-endoffsets-endoffsets indicate last block of each partition.

-nofreespace-nofreespace suppress all free space reporting.

-shims-shims report free space < 32 sectors

-uuids-uuids show per-instance UUIDs for each partition. APM does not store instance UUIDs

so these will be randomly generated for APM entries.

udifrezudifrez [options] image

embed resources (e.g. a software license agreement) in a disk image.

You must specify one of the following options:

-xml-xml file

Copy resources from the XML in file.

-rsrcfork-rsrcfork file

Copy resources from file's resource fork.-replaceall-replaceall

Delete all pre-existing resources in image.

udifderezudifderez [options] image

extract resources from image.

Options:

-xml-xml emit XML output (default)

-rez-rez emit Rez format output

Common options: -encryption-encryption, -stdinpass-stdinpass, and -srcimagekey-srcimagekey.

EXAMPLESEXAMPLES

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 named master.cdr

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

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


15/19

e use rea access o ev r s s no ava a e. o e use o e oc -spec a

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 image without user interaction:

printf 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 Apple_partition_scheme

/dev/disk2s1 Apple_partition_map

/dev/disk2s2 Apple_HFS /Volumes/Moby

ditto /Applications/Preview.app /Volumes/Moby

hdiutil detach /dev/disk2

hdiutil convert -format UDZO Moby.dmg -shadow

Using makehybrid to create cross-platform data with files overlapping between filesystem views. With

these files:

albumlist.txt song2.wma song4.m4a song6.mp3 song8.mp3

song1.wma song3.m4a song5.mp3 song7.mp3

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

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

will create an image with three filesystems pointing to the same blocks. The HFS+ filesystem, typi-

cally 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, typically the default filesystem for optical media on many platforms, will only

show the .mp3 files. All three filesystems will include the "albumlist.txt" files.

Image from directory (new-style):

hdiutil create -srcfolder mydir mydir.dmg

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

du -s m Folder # du 1 will count resource forks


16/19

10542

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

hdid -nomount folder.dmg

...

/dev/disk1s2 Apple_HFS

newfs_hfs -v myFolderImage /dev/rdisk1s2

hdiutil detach disk1

hdid folder.dmg

...

/dev/disk1s2 Apple_HFS /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 Apple_HFS /Volumes/myVolume

diskutil unmount disk1s2

mkdir /Volumes/myVolume

sudo mount -r -t hfs -o owners /dev/disk1s2 /Volumes/myVolume

# -o owners is the default for manual mounts

Forcing a known image to attach:

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

ENVIRONMENTENVIRONMENT

The following environment variables affect hdiutilhdiutil and DiskImages:

com_apple_hdid_verbose

enable -verbose-verbose behavior for attachattach.

com_apple_hdid_debug

enable -debug-debug behavior for attachattach.

com_apple_hdid_nokernel

similar to -nokernel-nokernel but works even with, for example, createcreate -attach-attach.

com_apple_hdid_kernel

attempt to attach in-kernel first (like attachattach -kernel-kernel). 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 attachattach -kernel-kernel is used or the corresponding variable is set. If an image is not

"kernel-compatible" and -kernel-kernel is specified, the attach will fail. (WARNING: ram:// images

currently use wired memory when attached in-kernel).

com_apple_diskimages_insecureHTTP

disable SSL peer verification the same way -insecurehttp-insecurehttp does. Useful for clients of

DiskImages such as asr(8) which don't support a similar command line option.

ERRORSERRORSDiskImages 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

our primary error domain: the BSD errno values. For debugging, -verbose-verbose should generally 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 explicitly by DiskImages when its

kernel driver or framework helper cannot be contacted. It also often shows up when

a device has been removed while I/O is still active. One common case of the helper

not being found is when Foundation's Distributed Objects RPC mechanism cannot be

configured. D.O. doesn't work under dead Mach bootstrap contexts such as can exist

in a reattached screen(1) session. Root users can take advantage of


17/19

context.

[EINVAL] Invalid argument. This error is used in many contexts and is often a clue that

hdiutilhdiutil's arguments are subtly non-sensical (e.g. an invalid layout name passed to

createcreate -layout-layout).

[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.

This error can also occur when the Resource fork of an old-style UDIF overflows.

[EAUTH] Authentication error. Used by DiskImages when libcurl(3) is unable to verify its

SSL peer or when Security.framework indicates that the user failed to enter the cor-rect password. See -insecurehttp-insecurehttp and -cacert-cacert for more information about verifica-

tion of SSL peers.

[EBUSY] Resource busy. Used if necessary exclusive access cannot be obtained. This error

often appears when a volume can't be unmounted.

[EAGAIN] Resource temporarily unavailable. As of OS X 10.5, DiskImages uses reader/writer

locks on its image files to prevent images from being attached on more than one

machine at a time (e.g. over the network). EAGAIN is returned if the appropriate

read or write lock can't be obtained.

EACCES vs. EPERM EACCES and EPERM are subtly different. The latter "operation not permitted" tends

to refer to an operation that cannot be performed, often due to an incorrect effec-

tive user ID. On the other hand, "permission denied" tends to mean that a particu-lar file access mode prevented the operation.

USINGUSING PERSISTENTPERSISTENT SPARSESPARSE IMAGESIMAGES

As of OS X 10.5, a more reliable, efficient, and scalable sparse format, UDSB (SPARSEBUNDLE), is recom-

mended for persistent sparse images as long as a backing bundle (directory) is acceptable. OS X 10.5

also introduced F_FULLFSYNC over AFP (on client and server), allowing proper journal flushes for HFS+J-

bearing images. Critical data should never be stored in sparse disk images on file servers that don't

support F_FULLFSYNC.

SPARSE (UDSP) 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 be avoided in favor of SPARSEBUNDLE

images or UDRW images and resizeresize.

If more space is needed than is referenced by the hosted filesystem, hdiutilhdiutil resizeresize or diskutil(8)

resizeresize can help to grow or shrink the filesystem in an image. compactcompact reclaims unused space in sparse

images. Though they request that hosted HFS+ filesystems use a special "front first" allocation pol-

icy, beware that sparse images can enhance the effects of any fragmentation in the hosted filesystem.

To prevent errors when a filesystem inside of a sparse image has more free space than the volume hold-

ing 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 cur-

rently only behaves this way as a result of a direct attachattach action and will not behave this way if, for

example, the filesystem is unmounted and remounted.

NOTENOTE ONON DEVDEV ENTRYENTRY ACCESSACCESS

Since any /dev entry can be treated as a raw disk image, it is worth noting 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 hdiutilhdiutil verbs such as fsidfsid or pmappmap with 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. convertconvert or createcreate -srcdevice-srcdevice


18/19

operations), while /dev/rdisk is usable for the quick pmappmap or fsidfsid. 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).

COMPATIBILITYCOMPATIBILITY

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 ver-

sions (at the expense of the performance and reliability improvements offered by the format enhance-

ments). 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 embed-

ded resource fork, and the default Disk Copy.app "compressed" format became UDZO (breaking compatibil-

ity with 10.0). OS X 10.4 introduced bzip2 compression in the UDBZ format which provides smaller

images (especially when combined with makehybridmakehybrid) 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, by default, be recognized by either OS X 10.1 or OS X 10.0. flattenflatten can be

used to customize the type of metadata stored in the image.

OS X 10.5 introduced sparse bundle images which compactcompact quickly but are not recognized by previous OS

versions. OS X 10.6 removed support for attaching SPARSEBUNDLE images from network file servers thatdon't support F_FULLFSYNC.

HISTORYHISTORY

Disk images were first invented to electronically store and transmit representations of floppy disks

for manufacturing replication. These images of floppies are typically referred to as 'Disk Copy 4.2'

images, in reference to the application that created 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.

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 Compression (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 rep-

resent entire block devices and all the data therein: DDM, partition map, disk-based drivers, etc. For

example, it can represent bootable CDs which can then be replicated from an image. To ensure single-

fork files (NDIF was dual-fork), it began embedding its resource fork in the data fork. 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 recognizes the filesystems. They can also be burned with hdiutilhdiutil

burnburn.

WHAT'SWHAT'S NEWNEW

In OS X 10.6, pmappmap was rewritten to use MediaKit's latest reporting routines so that it can properly

support GPT partition maps. Also -debug-debug now implies -verbose-verbose for all verbs.

OS X 10.5 changed the behavior of attachattach when run on an existing image or /dev node: if the image was

attached but no volume was mounted, the volume would be mounted. Prior systems would return the /dev

without mounting the volume. This change effectively removes the ability to create a second /dev node

from an existing one.

SEESEE ALSOALSO

authopen(1), hdid(8), diskutil, ditto(8), ioreg(8), drutil(1), ufs.util(8), msdos.util(8), hfs.util(8),

diskarbitrationd(8), /usr/sbin/disktool (run with no arguments for usage),

/System/Library/CoreServices/DiskImageMounter.app.

Mac OS X 22 Apr 2009 Mac OS X


19/19

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errorsReport errors in the content of this documentation with the feedback links below.

Bug reportsReport bugs in the functionality of the described tool or API through Bug Reporter.

Formatting problemsReport formatting mistakes in the online version of these pages with the feedback links

below.

Did this document help you? YesIt's good, but...Not helpful...

Mac Os x Manual Page - Hdiutil

Documents

Transcript of Mac Os x Manual Page - Hdiutil