manpages.info - online man pages   

Mac OS X / Darwin man pages : hdiutil (1)
hdiutil (1)

Table of Contents

Name

hdiutil - manipulate disk images

Synopsis

hdiutil verb [options]

Description

hdiutil uses the DiskImages framework to manipulate disk images. Common verbs include attach, detach, verify, create, convert, and burn.

The rest of the verbs are: help, info, load, checksum, chpass, eject (historical synonym for detach), flatten, unflatten, imageinfo, mount (historical synonym for attach), mountvol, unmount, plugins, internet-enable, resize, segment, compact, makehybrid, and pmap.

Common Options

All hdiutil verbs accept the following options:

-verbose 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.
-quiet
minimize output in most cases. -debug be very verbose. This option is good if a large amount of information about what hdiutil and the DiskImages framework are doing is needed. -debug and -verbose generate almost entirely independent outputs.

Many hdiutil verbs understand the following options:

-plist
display output in plist format

-srcimagekey key=value
specify a key/value pair for the disk image recognition system. (-imagekey is normally a synonym) -tgtimagekey key=value specify a key/value pair for any image created. (-imagekey is only a synonym if there is no input image).

-encryption [crypto_method]
specify a particular type of encryption or, if not specified, the default CEncryptedEncoding. CEncryptedEncoding utilizes the AES cipher with a 128 bit key.
-stdinpass
cause hdiutil to read a null-terminated passphrase from its standard input. ^@ can be typed to explicitly insert the terminator. -stdinpass is primarily for automation and does not currently suppress the terminal's current echo state when used interactively. -stdinpass replaces -passphrase though the latter is still supported for compatibility. -recover keychain_file specify a keychain containing a certificate (generated with -certificate) to unlock the image. -certificate certificate_file specify a secondary access certificate for the image being created. -cacert cert specify a certificate authority certificate. cert can be either a PEM file or a directory of certificates processed by c_rehash(1) . See also --capath and --cacert in curl(1) . -insecurehttp ignore SSL host validation failure. 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 [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 -shadow also accept -cacert and -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 filename and changes its behavior accordingly. For example, a sparse image can be created without specifying -type SPARSE simply by appending the .sparseimage extension to the provided filename.

Verbs

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.

help
display minimal usage information for each verb. hdiutil verb -help will provide full usage information for that verb.

attach image [options]
attach a disk image to the system as a device. attach, like hdid(8) , will return information about an already-attached image as if it had attached it. mount is a synonym for attach.

Beware that an image you have created and attached is a considered a new removable device. See hdid(8) and the EXAMPLES section below for more details.

Common options: -encryption, -stdinpass, -recover, -imagekey, -shadow, and -plist.

Options:

-readonly
force the resulting device to be read-only
-readwrite
attempt to override the DiskImages framework's decision to attach a particular image read-only. For example, -readwrite can be used to modify the HFS filesystem on a HFS/ISO hybrid CD image.
-nokernel
attach with a helper process.
-kernel
attempt to attach this image without a helper process; fail if not possible.
-notremovable
prevent this image from being detached. Only root can use this option.

-mount 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.
-nomount
identical to -mount suppressed.
-mountroot path
mount volumes in path instead of in /Volumes -mountpoint path assuming only one volume, mount it at path instead of in /Volumes
-union
perform a union mount
-private
suppress mount notifications to the rest of the system.
-nobrowse
mark the volumes non-browsable in applications such as the Finder.
-owners on|off
enable or disable owners for HFS+ volumes, potentially overriding the system's default value for the volume. -drivekey 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:

-[no]verify
do [not] suppress verification of the image. By default hdiutil attach verifies all images containing checksums before attaching them. To maintain backwards compatibility, hdid(8) does not attempt to verify images before attaching them. -[no]ignorebadchecksums specify whether bad checksums should be ignored. The default is to abort when a bad checksum is detected.
-[no]idme
do [not] perform IDME actions on IDME images. IDME actions are normally only performed when a browser downloads and attaches an image.
-[no]idmereveal
do [not] reveal (in the Finder) the results of IDME processing.
-[no]idmetrash
do [not] put IDME images in the trash after processing.
-[no]autoopen
do [not] auto-open volumes (in the Finder) after attaching an image. By default, readonly volumes are auto-opened in the Finder.
-[no]autoopenro
do [not] auto-open read-only volumes.
-[no]autoopenrw
do [not] auto-open read/write volumes.

detach dev_name [-force]
detach a disk image and terminate any associated hdid process. dev_name is a partial /dev node path (e.g. disk1"). If Disk Arbitration is running, detach will use it to unmount any partitions and detach the image. If not, detach 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. eject is a synonym for detach.

Options:
-force Similar to umount -f. Unmounts any filesystems and detaches the image, regardless of any open files on the image.

verify image [options]
compute the checksum of a read-only (or compressed) image, and verify it against the value stored in the image. verify accepts the common options -encryption, -stdinpass, -srcimagekey, and -plist.

create size_spec image
create a new image of the given size. If image already exists, -ov must be specified or create will fail. If image is attached, it must be detached before it can be overwritten, even if -ov is specified.

The size specified is the size of the image file. Filesystem and partition layout overhead (64 sectors for the default SPUD layout) will be deducted before space is made for user data in any volume on the image.
Size specifiers:
-size ??b|??k|??m|??g|??t??p|??e
-size specifies 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 occasionally useful when creating large sparse images. -sectors sector_count
Specify the size of the image file in 512 byte sectors. -megabytes size
Specify the size of the image file in megabytes (1024*1024 bytes).
-srcfolder directory
specifies the image size based on the contents of directory. -srcfolder also specifies that the contents of directory should populate the resulting image. -srcfolder copies file by file, creating an optimized filesystem on the destination image (which then could be restored by asr(8) ). -srcdir is a synonym for -srcfolder.

Common options: -encryption, -stdinpass, -plist, -imagekey, -tgtimagekey, and -plist. -imagekey di-sparse-puma-compatible=TRUE and -imagekey di-shadow-puma-compatible=TRUE will create, respectively, sparse and shadow images that can be attached on OS X 10.1.

General options:
-align alignment
specifies a size to which the final data partition will be aligned. The default is 4K. -type UDIF|SPARSE
UDIF is the default disk image format. If specified, a UDRW of the specified size will be created. Specifying SPARSE creates a UDSP: a read/write image which expands as is is filled with data. The default is to grow one megabyte at a time, but the key sparse-band-size can be used (with -imagekey) to specify the number of sectors that will be added each time the image grows. The maximum size of a SPARSE image is bounded by the filesystem in the image. Keep in mind that resize can resize an HFS+ filesystem within initially-defined stretch limits.

SPARSE images (and shadow files) are designed to be used during intermediate steps in the process of creating other images (e.g. UDZO) when the final image sizes are unknown. Such growable images should not generally be used for persistent storage because their internal structure exacerbates any fragmentation introduced by the filesystem. compact can reclaim some unused space in a SPARSE image containing an HFS filesystem. -fs filesystem
where filesystem is one of HFS+, HFS+J, HFSX, HFS, MS-DOS, or UFS. -fs may also change the default layout if that particular filesystem is not native to an Apple Partition Map. -volname volname
The newly-created filesystem will be named volname. The default name is `untitled'.

-uid 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) ).
-gid gid
the root of the newly-created volume will be owned by the given numeric group id. 99 maps to `unknown'.
-mode mode
the root of the newly-created volume will have mode mode.
-nouuid
suppress addiing a UUID to the volume. Such a volume will behave more like a volume which was formatted with OS 9 or earlier. -[no]autostretch do [not] suppress automatically making stretchable volumes when the volume size crosses the auto-stretch-size threshhold (default: 50 MB). See also asr(8) . -stretch max_stretch -stretch initializes HFS+ filesystem data such that it can later be stretched using hdiutil resize. max_stretch is specified like -size. -fsargs newfs_args additional arguments to pass to whatever newfs program is implied by -fs. -layout layout Specify the partition layout of the image. layout can be anything specified in MediaKit.framework's MKDrivers.bundle. 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 is an acronym for Single Partition UDIF. SPUD creates an image with a DDM and an Apple Partition Scheme partition map with a single entry for an Apple_HFS 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 -fs, the default is SPUD. Other layouts include UNIVERSAL HD and UNIVERSAL 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. -partitionType partition_type Change the type of partition in a SPUD. The default is Apple_HFS. The principal alternative is Apple_UFS, though the appropriate partition type will be automatically chosen depending on the argument to -fs.
-ov
overwrite an existing file. The default is not to overwrite existing files. See the note with create about not being allowed to overwrite attached images.
-attach
attach the image after creating it. Note that if no filesystem is specified via -fs, the attach will fail per the default attach -mount required behavior. Image from directory options (for -srcfolder): -format format Specify the final image format. The default is UDZO. format can be any of the format parameters used by create. -[no]crossdev do [not] cross device boundaries when copying from the source.
-[no]scrub
do [not] skip temporary files when imaging volumes. Scrubbing is only the default when the argument to -srcfolder is a the root of a volume. Such files include trashes, temporary folders, swap files, etc. -[no]anyowners do [not] require that the user invoking hdiutil own all of the files being copied. create normally prompts for authentication if it detects a file owned by someone other than the user creating the image so that the ownership of the files will be maintained in the image.

convert image -format format -o 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 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 (growable with content) 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 non-read/write image formats completely remove unused space in HFS and UFS filesystems. For UDZO, -imagekey zlib-level=value allows you to set the zlib compression level ala gzip(1) . The default compression level is 1 (fastest).

Options are any of:

Common options: -encryption, -stdinpass, -certificate, -srcimagekey, -tgtimagekey, -shadow with friends, and -plist.

Other options:
-align alignment
The default is 4 (2K).

-pmap
add partition map. When converting a NDIF to a any variety of UDIF, or when converting an unpartitioned UDIF, the default is true. -segmentSize [sector_count] Specify segmentation into sector_count-sized segments as outfile is being written. The default sector_count when -segmentSize is specified alone is 2*1024*1024 (1 GB segments) for UDTO images and 4*1024*1024 (2 GB segments) for all other image types. sector_count can also be specified ??b|??k|??m|??g|??t??p|??e like create's -size flag. -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.

burn 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 are: -shadow with friends, -srcimagekey, -encryption, and -stdinpass.

Other options:

-device
specify a device to use for burning. See -list.
-testburn
don't turn on laser (laser defaults to on).
-anydevice
allow burning to devices not qualified by Apple.

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

-[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 partition 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 optical media. The default is to add the partition map if needed.

-[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 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 different checksum than the image it came from. The default is to burn all blocks of the disk image (minus any trailing Apple_Free).

-nounderrun
turn off buffer underrun protection.

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

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

-sizequery
calculate the size of disc required (the size returned is in sectors) without burning anything.

-erase
prompt for optical media (DVD-RW/CD-RW) and then, if the hardware supports it, quickly erase the media.
-fullerase
erase all sectors of the disc (this usually takes quit a bit longer than -erase).
-list
list all burning devices, with OpenFirmware paths suitable for -device.

makehybrid -o image source
Generate a disk image image using source with the DiscRecording framework's content creation system. source can either be a directory or a disk image. The generated image can later be burned using hdiutil burn, or converted to a read-only disk image with hdiutil convert. The generated filesystem is not designed to be used read/write, but can safely have its files copied to a read/write filesystem by ditto(8) or asr(8) .

Filesystem options:

-hfs
Generate an HFS+ filesystem. This filesystem can be present on an image simultaneously with an ISO9660 or Joliet filesystem. On operating systems that understand HFS+ as well as ISO9660, like Mac OS 9 or Mac OS X, it is usually the preferred filesystem.
-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 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 Joliet filesystem is present on a disk image or CD, but not HFS+, Mac OS X will use the ISO9660 (or Joliet) filesystem. -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 ISO9660 filesystem. Joliet supports Unicode filenames, but is only supported on some operating 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.

By default, if no filesystem is specified, the image will be created with all three filesystems 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 metadata 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 Path to folder which should be blessed for Mac OS X booting on the generated filesystem. This assumes the folder has been otherwise prepared, for example with bless -bootinfo to create a valid BootX file. (HFS+ only).

-hfs-openfolder
Path to a folder that will be opened by the Finder automatically. See also the -openfolder option in bless(8) (HFS+ only). -hfs-startupfile-size Allocated an empty HFS+ Startup File of the specified size, in bytes (HFS+ only).

-abstract-file
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).
-bibliography-file
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).
-copyright-file
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).
-application
Application string (ISO9660/Joliet).
-preparer
Preparer string (ISO9660/Joliet).
-publisher
Publisher string (ISO9660/Joliet).
-system-id
System Identification string (ISO9660/Joliet).
-keep-mac-specific
Expose Macintosh-specific files (such as .DS_Store) in non-HFS+ filesystems (ISO9660/Joliet).

-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
Volume name for just the HFS+ filesystem if it should be different (HFS+ only).
-iso-volume-name
Volume name for just the ISO9660 filesystem if it should be different (ISO9660 only).
-joliet-volume-name
Volume name for just the Joliet filesystem if it should be different (Joliet only).

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

-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
Instead of using command-line parameters, use a standard plist from standard 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 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 your 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 drutil filename myname to see how a given string would be remapped.

The -abstract-file, -bibliography-file, -and -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.

compact image
scans the bands of a SPARSE type disk image with an HFS filesystem in it, removing those parts of the image file which are no longer being used by the filesystem. Depending on the layout of files in the filesystem, compact may or may not shrink the image file. Common Options: -encryption, -stdinpass, -srcimagekey, -shadow with friends, and -plist.

info
display information about DiskImages.framework, the disk image driver, and any images that are currently attached. hdiutil info accepts -plist.

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

checksum image -type type
Calculate the specified checksum on the image data, regardless of image type. Common options: -shadow with friends, -encryption, -stdinpass. -srcimagekey, and -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

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

Common options are: -recover and -srcimagekey. The options -oldstinpass and -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.

unflatten image
unflatten a read-only (or compressed) UDIF disk image, creating a dual-fork file in traditional format (resource-only; no XML). Common options: -encryption, -stdinpass, and -srcimagekey.

flatten image
Flatten a read-only (or compressed) UDIF disk image into a single-fork file. If the image is UDZO format and does not contain XML meta-data for in-kernel attachment, it will be added. Common options are: -srcimagekey, -encryption, and -stdinpass. flatten is only required if the UDIF has previously been unflatten'd.

Other options:

-noxml
don't embed XML data for in-kernel attachment. The image will never attach in-kernel. -norsrcfork don't embed resource fork data. The image will not attach on OS X versions prior to OS X 10.2.

hfsanalyze image
Print information about an HFS/HFS+ volume. As is usually the case, image can be a /dev entry corresponding to a physical disk. See the NOTE ON DEV ENTRY ACCESS section.

Common options are: -encryption, -stdinpass, -srcimagekey, and -shadow with friends.

mountvol dev_name
Attempt to mount dev_name using Disk Arbitration (similar to diskutil mount). XML output is available from -plist. Note that mountvol (rather than mount) will remount a volume after it has been unmounted by unmount. mount/attach can be called on a /dev entry, but it will treat the /dev entry as a disk image to be attached (creating another /dev entry). This is usually undesirable.

unmount volume [-force]
unmounts a mounted volume. volume can be a full path to a /dev entry or the name of a mountpoint.

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

imageinfo image
Print out information about a disk image. Common options are: -encryption, -stdinpass, -srcimagekey, -shadow with friends, and -plist.

Options are any of:

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

plugins
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). -plist is available.

internet-enable [-yes] | -no | -query 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 are: -encryption, -stdinpass, -srcimagekey, and -plist.

resize size_spec image
Given a read/write partitioned UDIF, if the last partition is Apple_HFS, attempt to resize the partition to the end of the image file, or to the last used block in the embedded HFS/HFS+ file system (depending on size_spec). resize is typically used when working with a large device image when it is desirable to shrink the HFS/HFS+ partition before converting to CD-R/DVD-R format. resize can also be used to grow a filesystem within its predefined stretch limits.

hdiutil burn 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 image filesystem (assuming minimal data fragmentation).

Common options are: -encryption, -stdinpass, -srcimagekey, -shadow with friends, and -plist.

Size specifiers:
-size ??b|??k|??m|??g|??t??p|??e
-sectors sector_count | 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 automatically determines the largest size to which the partition can be grown and then uses that value.

Other options:

-imageonly
only resize the image file, not the partition(s) inside of it. This is the default for UDIF images (more partitions can then be added in the new free space).
-partitiononly
only resize the partition(s) in the image (including their embedded filesystems). This is the default for NDIF images. For a newlycreated SPUD where the partition fills the image, the partition can only be shrunk. If there is an Apple_Free partition after an existing partition, that partition can be expanded into the space marked by the Apple_Free. Shrinking a partition results in a larger Apple_Free partition. -partitionNumber partitionNumber specifies which partition to resize (UDIF only -- see HISTORY below). partitionNumber is 0-based, but, per hdiutil pmap, partition 0 is the partition map itself.

-growonly
only allow the image to grow
-shrinkonly
only allow the image to shrink
-nofinalgap
allow resize to entirely eliminate the trailing 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.

-limits
Displays the minimum, current, and maximum sizes (in 512 byte sectors) that could be passed given possible -imageonly or -partitiononly flags. Does not modify the image file.

segment
segment -o firstSegname -segmentCount #segs image [opts] segment -o firstSegname -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. Common options are: -encryption, -stdinpass, -srcimagekey, -tgtimagekey, and -plist.

Options:
-segmentCount segment_count
Specify the number of segments. Only one of -segmentCount or -segmentSize will be honored. -segmentSize segment_size
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 -segmentCount or -segmentSize will be honored. Segmenting read/write (UDRW) images is not supported (as of OS X 10.3).

-firstSegmentSize segment_size
Specify the first segment size in sectors in the same form as for -segmentSize. Used for multi-CD restores. -restricted Make restricted segments for use in multi-CD restores.

pmap image_source [-options optstr]
display the partition map of an image or device. image_source is either a plain file or special file (i.e. a /dev/disk entry). See the NOTE ON DEV ENTRY ACCESS below. Common options are: -encryption, -stdinpass, -srcimagekey, and -shadow 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

Examples

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.dmgparg, 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 1 GB sparse image (a 1 GB filesystem in a growable file): hdiutil create -type SPARSE -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 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, 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. 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}'

Image from folder (new-style):
hdiutil create -srcfolder mydir mydir.dmg

Image from folder (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
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
# when you are 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 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

Note on Dev Entry Access

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 hdiutil verbs such as hfsanalyze 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. convert operations), while /dev/rdisk is usable for the quick pmap or hfsanalyze. In particular, creating a read-only image from a mounted journaled filesystem will prevent the volume in the image from mounting (because the journal will be permanently dirty).

Compatibility

Several new features were introduced into the DiskImages framework with OS X 10.1 and OS X 10.2. Sparse images, encrypted images, and zlib-compressed images all did not exist in OS X 10.0.x but came into being with 10.1. These images will not attach (or will attach read/write allowing for their destruction) on OS X 10.0.x. There are multiple types of sparse and shadow images; various keys (documented above) can be passed to ensure the compatibility desired is achieved.

With OS X 10.2, in-kernel attachment became possible, image meta-data could be stored XML, and the default Disk Copy.app compressed format became UDZO. It is now possible to create images that won't attach on OS X 10.1 and easy to create images that won't attach on OS X 10.0. SPARSE images should not be expected to be backwards compatible (mounting on older systems than created them).

History

Originally, disk images were invented to electronically store and transmit representations of floppy disks for manufacturing replication. These images are typically referred to as `Disk Copy 4.2' images, in reference 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, as well as provide the ability to create images larger than a floppy disk. Additionally, compression and the ability to attach disk images to Mac OS 9 as mass storage devices was introduced. NDIF images were created and manipulated by Disk Copy version 6.

UDIF (Universal Disk Image Format) device images go beyond NDIF, allowing the creation of device images which include data that might appear on a given mass storage device (DDM, Apple partition scheme partition map, disk-based drivers, etc). This format allows items such as bootable CD's to be created from an image. UDIF is a flat file format (vs. NDIF which is a dual fork format), and is the native image format for OS X.

Raw disk images from other operating systems (e.g. .iso files) can be mounted if they contain data which OS X can interpret as a filesystem. They can also be burned with hdiutil burn.

What's New

As of Mac OS X 10.3, most Disk Copy functionality moved to Disk Utility and a new background application DiskImageMounter attaches images for the Finder. hdiutil features the new verbs makehybrid, compact, and chpass. create has undergone a number of enhancements, most notably the ability to create an image directly from a source directory. All framework clients now use the same diskimages-helper background process for processing images, including applications such as Safari.

See Also

authopen(1) , hdid(8) , diskutil, ditto(8) , load_hdi(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.


Table of Contents