Advertisement
Not a member of Pastebin yet?
Sign Up,
it unlocks many cool features!
- HDIUTIL(1) BSD General Commands Manual HDIUTIL(1)
- NAME
- hdiutil -- manipulate disk images (attach, verify, burn, etc)
- SYNOPSIS
- hdiutil verb [options]
- DESCRIPTION
- hdiutil uses the DiskImages framework to manipulate disk images. Common verbs include attach, detach,
- verify, create, convert, compact, and burn.
- The rest of the verbs are currently: help, info, checksum, chpass, unflatten, flatten, imageinfo,
- isencrypted, mountvol, unmount, plugins, udifrez, udifderez, internet-enable, resize, segment,
- makehybrid, and pmap.
- BACKGROUND
- 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, verify verifies that the blocks stored in
- a read-only disk image have not changed since it was created. On the other hand, create -srcfolder
- creates a disk image container, puts a filesystem in it, and then copies the specified files to the new
- filesystem.
- COMMON OPTIONS
- The following option descriptions apply to all verbs:
- -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 close stdout and stderr, leaving only hdiutil's exit status to indicate success or failure.
- -debug and -verbose disable -quiet.
- -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 enables -verbose.
- Many hdiutil verbs understand the following options:
- -plist provide result output in plist format. Other programs invoking hdiutil are expected to
- use -plist rather than try to parse the human-readable output. The usual output is
- consistent but generally unstructured.
- -puppetstrings provide progress output that is easy for another program to parse. PERCENTAGE outputs
- can include the value -1 which means hdiutil is performing an operation that will take
- an indeterminate amount of time to complete. Any program trying to interpret hdiutil's
- progress should use -puppetstrings.
- -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 [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 read a null-terminated passphrase from standard input. If the standard input is a tty,
- the passphrase will be read with readpassphrase(3). -stdinpass replaces -passphrase
- though the latter is still supported for compatibility. Beware that the password will
- contain any newlines before the NULL. See EXAMPLES.
- -agentpass force the default behavior of prompting for a passphrase. Useful with -pubkey to cre-
- ate an image protected by both a passphrase and a public key.
- -recover keychain_file
- specify a keychain containing the secret corresponding to the certificate specified
- with -certificate when the image was created.
- -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 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 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 and --cacert in
- curl(1).
- -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 [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. hdiutil verbs taking images as input
- accept -shadow, -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 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.
- 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 basic
- usage information for that verb.
- attach image [options]
- attach a disk image as a device. attach will return information about an already-attached
- image as if it had attached it. mount is a poorly-named synonym for attach. 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 attach 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, -stdinpass, -recover, -imagekey, -shadow, -puppetstrings, and
- -plist.
- Options:
- -readonly force the resulting device to be read-only
- -readwrite attempt to override the DiskImages framework's decision to attach a par-
- ticular 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. This is again the default as of OS X 10.5.
- -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 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. The
- default is required (attach will fail if no filesystems mount).
- -nomount identical to -mount suppressed.
- -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 path like -mountroot, but mount point directory names are randomized with
- mkdtemp(3).
- -mountpoint path assuming only one volume, mount it at path instead of in /Volumes. See
- fstab(5) for ways a system administrator can make particular volumes
- automatically mount in particular filesystem locations by editing the
- file /etc/fstab.
- -union attempt a union mount over the mount point specified by -mountpoint.
- Union mounts are no longer supported in Mac OS X, so this flag is cur-
- rently a no-op.
- -private suppress filesystem mount notifications. -private confuses programs
- using the Carbon File Manager and should be avoided in favor of
- -nobrowse.
- -nobrowse render any volumes invisible in applications such as the OS X Finder.
- -owners on|off specify that owners on any filesystems be honored or not.
- -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 do [not] verify the image. By default, hdiutil attach attempts to intel-
- ligently verify images that contain checksums before attaching them. If
- hdiutil can write to an image it has verified, attach 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,
- skip-previously-verified
- -[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 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 do [not] reveal (in the Finder) the results of IDME processing.
- Preferences key: skip-idme-reveal
- -[no]idmetrash do [not] put IDME images in the trash after processing.
- Preferences key: skip-idme-trash
- -[no]autoopen do [not] auto-open volumes (in the Finder) after attaching an image. By
- default, read-only volumes are opened in the Finder.
- -[no]autoopenro do [not] auto-open read-only volumes.
- Preferences key: auto-open-ro-root
- -[no]autoopenrw do [not] auto-open read/write volumes.
- Preferences key: auto-open-rw-root
- -[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
- detach dev_name [-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, detach will use it to unmount any filesystems 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 ignore open files on mounted volumes, etc.
- verify 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.
- verify accepts the common options -encryption, -stdinpass, -srcimagekey, -puppetstrings, and
- -plist.
- create size_spec image
- create a new image of the given size or from the provided data. If image already exists,
- -ov must be specified or create will fail. To make a cross-platform CD or DVD, use
- makehybrid 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 ??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 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 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. Other size specifiers, such
- as -size, will override the default size calculation based on the source content,
- allowing for more or less free space in the resulting filesystem. -srcfolder can
- be specified more than once, in which case the image volume will be populated at
- the top level with a copy of each specified filesystem object. -srcdir is a syn-
- onym.
- -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. resize can be used to adjust the size
- of resizable filesystems and writable images. Both -srcdevice and -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, -volname, -stretch, or -size) are
- invalid and ignored when using -srcdevice.
- Common options: -encryption, -stdinpass, -certificate, -pubkey, -plist, -imagekey,
- -tgtimagekey, -puppetstrings, 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. -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 alignment
- specifies a size to which the final data partition will be aligned. The default
- is 4K.
- -type UDIF|SPARSE|SPARSEBUNDLE
- -type is particular to create and is used to specify the format of empty
- read/write images. It is independent of -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
- 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. compact can reclaim unused
- bands in sparse images backing HFS+ filesystems. resize will only change the vir-
- tual size of a sparse image. See also USING PERSISTENT SPARSE IMAGES below.
- -fs filesystem
- where filesystem is one of HFS+, HFS+J (JHFS+), HFSX, JHFS+X, MS-DOS, or UDF. -fs
- causes a filesystem of the specified type to be written to the image. -fs may
- change the partition scheme and type appropriately. -fs will not make any size
- adjustments: if the image is the wrong size for the specified filesystem, create
- will fail. -fs is invalid and ignored when using -srcdevice.
- -volname volname
- The newly-created filesystem will be named volname. The default depends the
- filesystem being used; HFS+'s default volume name is `untitled'. -volname is
- invalid and ignored when using -srcdevice.
- -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 (in octal) mode. The default
- mode is determined by the filesystem's newfs unless -srcfolder is specified, in
- which case the default mode is derived from the specified filesystem object.
- -[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 max_stretch
- -stretch initializes HFS+ filesystem data such that it can later be stretched on
- older systems (which could only stretch within predefined limits) using hdiutil
- resize or by asr(8). max_stretch is specified like -size. -stretch is invalid
- and ignored when using -srcdevice.
- -fsargs newfs_args
- additional arguments to pass to whatever newfs program is implied by -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 HFS+ and pass-
- ing arguments such as -c c=64,a=16,e=16 to -fsargs will minimize gaps at the front
- of the filesystem, allowing resize to squeeze more space from the filesystem. For
- truly optimal filesystems, use makehybrid.
- -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 single
- entry 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, the default layout is `GPTSPUD' (PPC systems used `SPUD'
- prior to OS X 10.6). Other layouts include `MBRSPUD' and `ISOCD'. create -help
- lists all supported layouts.
- -library bundle
- specify an alternate layout library. The default is MediaKit's MKDrivers.bundle.
- -partitionType partition_type
- Change the type of partition in a single-partition disk image. The default is
- Apple_HFS unless -fs implies otherwise.
- -ov overwrite an existing file. The default is not to overwrite existing files.
- -attach attach the image after creating it. If no filesystem is specified via -fs, the
- attach will fail per the default attach -mount required behavior.
- Image from source options (for -srcfolder and -srcdevice):
- -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 convert.
- Options specific to -srcdevice:
- -segmentSize size_spec
- Specify that the image should be written in segments no bigger than size_spec
- (which follows -size conventions).
- Options specific to -srcfolder:
- -[no]crossdev do [not] cross device boundaries on the source filesystem.
- -[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 do not fail if the user invoking hdiutil can't ensure correct file ownership
- for the files in the image.
- -skipunreadable skip files that can't be read by the copying user and don't authenticate.
- -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 or -skipunreadable
- must be used to prevent the operation from failing.
- By default, create -srcfolder attempts to maintain the permissions present in the source
- 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.
- convert image -format format -o outfile
- convert image to type format and write the result to outfile.
- As with create, the correct filename extension will be added only if it isn't part of the
- provided name. Format is one of:
- UDRW - UDIF read/write image
- UDRO - UDIF read-only image
- UDCO - UDIF ADC-compressed image
- UDZO - UDIF zlib-compressed image
- UDBZ - UDIF bzip2-compressed image (OS X 10.4+ only)
- UFBI - UDIF entire image with MD5 checksum
- UDRo - UDIF read-only (obsolete format)
- UDCo - UDIF compressed (obsolete format)
- UDTO - DVD/CD-R master for export
- UDxx - UDIF stub image
- UDSP - SPARSE (grows with content)
- UDSB - SPARSEBUNDLE (grows with content; bundle-backed)
- RdWr - NDIF read/write image (deprecated)
- Rdxx - NDIF read-only image (Disk Copy 6.3.3 format)
- ROCo - NDIF compressed image (deprecated)
- Rken - NDIF compressed (obsolete format)
- DC42 - Disk Copy 4.2 image
- In addition to the compression offered by some formats, the UDIF and NDIF read-only formats
- skip unused space in HFS, UFS, and MS-DOS (FAT) filesystems. For UDZO, -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, -stdinpass, -certificate, -srcimagekey, -tgtimagekey, -shadow
- and related, -puppetstrings, 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 unparti-
- tioned UDIF, the default is true.
- -segmentSize [size_spec]
- Specify segmentation into size_spec-sized segments as outfile is being written.
- The default size_spec when -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
- 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: -shadow and
- related, -srcimagekey, -encryption, -puppetstrings, 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 explicitly allow burning to devices not qualified by Apple (kept for back-
- wards compatibility as burn will burn to any device by default as of OS X
- 10.4).
- -[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 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 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 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 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 Disable the default buffer underrun protection.
- -[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 not
- be legally burned to a 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. The speed factor is relative to the media being burned
- (e.g. -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 calculate the size of disc required (the size returned is in sectors) with-
- out burning anything.
- -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 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 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 burn, or converted to another read-only format with convert. 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).
- hdiutil 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.
- Filesystem options:
- -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 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 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 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 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 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 to create a valid
- BootX file. (HFS+ only).
- -hfs-openfolder Path to a directory that will be opened by the Finder automatically.
- See also the -openfolder option in bless(8) (HFS+ only).
- -hfs-startupfile-size Allocate 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 gen-
- erated 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 gen-
- erated 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 gen-
- erated 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).
- -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 or -hard-disk-boot must be used to enable "No
- Emulation" or "Hard Disk Emulation" mode, respectively
- (ISO9660/Joliet).
- -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 Use El Torito No Emulation mode. The system firmware will load the
- number of sectors specified by -boot-load-size and execute it, with-
- out emulating any devices (ISO9660/Joliet).
- -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 For a No Emulation boot image, load the data at the specified segment
- address. This options is not recommended, so that the system
- firmware can use its default address (ISO9660/Joliet)
- -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 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 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 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 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 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).
- -udf-volume-name Volume name for just the UDF filesystem if it should be different
- (UDF 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). Per above, the Joliet hier-
- archy will supersede the ISO hierarchy when the hybrid is mounted as
- an ISO 9660 filesystem on Mac OS X. Therefore, if Joliet is being
- generated (the default) -hide-joliet will also be needed to hide the
- file from mount_cd9660(8).
- -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
- effectively supersedes -hide-iso when the resulting filesystem is
- mounted as ISO on OS X.
- -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 A glob expression of objects that should only be exposed in UDF.
- -only-iso A glob expression of objects that should only be exposed in ISO.
- -only-joliet A glob expression of objects that should only be exposed in Joliet.
- -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 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".
- 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 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 (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, compact may or may not shrink
- the image. For SPARSEBUNDLE images, completely unused band files are simply removed.
- Common options: -encryption, -stdinpass, -srcimagekey, -shadow and related, -puppetstrings,
- and -plist.
- info display information about DiskImages.framework, the disk image driver, and any images that
- are currently attached. hdiutil info accepts -plist.
- checksum image -type type
- Calculate the specified checksum on the image data, regardless of image type.
- Common options: -shadow and related, -encryption, -stdinpass. -srcimagekey, -puppetstrings,
- 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
- SHA - SHA
- SHA1 - SHA-1
- SHA256 - SHA-256
- SHA384 - SHA-384
- SHA512 - SHA-512
- chpass image
- change the passphrase for an encrypted image. The default is to change the password inter-
- actively.
- Common options: -recover and -srcimagekey. The options -oldstdinpass 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 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, -stdinpass, and -srcimagekey.
- flatten 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, -encryption, and -stdinpass. Since images are created "flat"
- by default, flatten is only required if the UDIF has previously been unflattened.
- 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.
- fsid 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, -stdinpass, -srcimagekey, and -shadow and related.
- mountvol dev_name
- mount the filesystem in dev_name using Disk Arbitration (similar to diskutil(8)'s mount).
- XML output is available from -plist. Note that mountvol (rather than mount, 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 unmount.
- Prior to OS X 10.5, mount/attach would treat a /dev entry as a disk image to be attached
- (creating another /dev entry). That behavior was undesirable.
- unmount volume [-force]
- unmount a mounted volume without detaching any associated image. Volume is a /dev entry or
- mountpoint. NOTE: unmount does NOT detach any disk image associated with the volume.
- Images are attached and detached; volumes are mounted and unmounted. mountvol will remount
- a volume that has been unmounted by unmount.
- 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: -encryption, -stdinpass, -srcimagekey, -shadow and related, and -plist.
- Options are any of:
- -format just print out the image format
- -checksum just print out the image checksum
- isencrypted image
- print a line indicating whether image is encrypted. If it is, additional details are
- printed.
- Common options: -plist.
- 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).
- Common options: -plist.
- internet-enable [-yes] | -no | -query image
- Enable or disable download post-processing (IDME). -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, -stdinpass, -srcimagekey, and -plist.
- resize 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,
- and the filesystem within it by aligning the end of the latter with the end of the image.
- On older systems, resize was limited to pre-defined limits that depended on how the filesys-
- tem was created. As of OS X 10.4, resize can be used to grow an HFS filesystem within an
- image to any size supported by HFS and the filesystem hosting the image.
- resize 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 resize does not move data. diskutil(8) resize can be used to move filesystem
- data so that hdiutil resize can make an image barely larger than the data within it.
- -fsargs can sometimes be used to minimize filesystem gaps in the image contents. resize 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+).
- 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 hosted filesystem (assuming minimal data fragmentation).
- Common options: -encryption, -stdinpass, -srcimagekey, -shadow and related, and -plist.
- Size specifiers:
- -size ??b|??k|??m|??g|??t??p|??e
- -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 only resize the image file, not the partition(s) and filesystems inside of
- it.
- -partitiononly only resize a partition / filesystem in the image, not the image.
- -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
- specifies which partition to resize (UDIF only -- see HISTORY below).
- partitionNumber is 0-based, but, per hdiutil pmap, partition 0 is the par-
- tition 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 in an APM
- map. Restoring such images to very old hardware may interfere with boot-
- ing.
- -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 does not modify the image.
- 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. Note: whether or
- not the segments are encrypted is determined by the options passed to segment and not by the
- state of the source image.
- Common options: -encryption, -stdinpass, -srcimagekey, -tgtimagekey, -puppetstrings, 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 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 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.
- -ov overwrite any existing files.
- pmap [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, -stdinpass, -srcimagekey, and -shadow and related.
- -simple generate MediaKit's minimal report: partition types, names, and sizes in
- human-readable units.
- -standard generate MediaKit's standard report, which adds partition offsets and uses
- 512-byte sectors.
- -complete generate MediaKit's comprehensive report, with end offsets, significant free
- space, etc.
- -endoffsets indicate last block of each partition.
- -nofreespace suppress all free space reporting.
- -shims report free space < 32 sectors
- -uuids show per-instance UUIDs for each partition. APM does not store instance UUIDs
- so these will be randomly generated for APM entries.
- udifrez [options] image
- embed resources (e.g. a software license agreement) in a disk image.
- You must specify one of the following options:
- -xml file
- Copy resources from the XML in file.
- -rsrcfork file
- Copy resources from file's resource fork.
- -replaceall
- Delete all pre-existing resources in image.
- udifderez [options] image
- extract resources from image.
- Options:
- -xml emit XML output (default)
- -rez emit Rez format output
- Common options: -encryption, -stdinpass, and -srcimagekey.
- 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.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
- be used if read access to /dev/rdisk1 is not available. Note use of the block-special
- device.
- Burning:
- hdiutil burn myImage.dmg
- Burns the image to available optical media and verifies the burn.
- hdiutil burn myRawImage.cdr -noverifyburn -noeject
- Burns the image without verifying the burn or ejecting the disc. Volumes will be
- mounted after burning.
- Creating a 50 MB encrypted image:
- hdiutil create -encryption -size 50m e.dmg -fs HFS+J
- Creating a 50 MB encrypted image protected with public key only:
- hdiutil create -encryption -size 50m e.dmg -fs HFS+J
- -pubkey F534A3B0C2AEE3B988308CC89AA04ABE7FDB5F30
- Creating a 50 MB encrypted image protected with public key and password:
- hdiutil create -encryption -size 50m e.dmg -fs HFS+J -agentpass
- -pubkey F534A3B0C2AEE3B988308CC89AA04ABE7FDB5F30
- Creating an encrypted single-partition 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 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 # 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
- ENVIRONMENT
- The following environment variables affect hdiutil and DiskImages:
- com_apple_hdid_verbose
- enable -verbose behavior for attach.
- com_apple_hdid_debug
- enable -debug behavior for attach.
- com_apple_hdid_nokernel
- similar to -nokernel but works even with, for example, create -attach.
- com_apple_hdid_kernel
- attempt to attach in-kernel first (like attach -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 attach -kernel is used or the corresponding variable is set. If an image is not
- "kernel-compatible" and -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 does. Useful for clients of
- DiskImages such as asr(8) which don't support a similar command line option.
- ERRORS
- DiskImages uses many frameworks and can encounter many error codes. In general, it tries to turn these
- errors numbers into localized strings for the user. For background, intro(2) is a good explanation of
- our primary error domain: the BSD errno values. For debugging, -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
- StartupItemContext(8) (in /usr/libexec) to access the startup item Mach bootstrap
- context.
- [EINVAL] Invalid argument. This error is used in many contexts and is often a clue that
- hdiutil's arguments are subtly non-sensical (e.g. an invalid layout name passed to
- create -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 and -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.
- USING PERSISTENT SPARSE IMAGES
- 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 resize.
- If more space is needed than is referenced by the hosted filesystem, hdiutil resize or diskutil(8)
- resize can help to grow or shrink the filesystem in an image. compact 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 attach action and will not behave this way if, for
- example, the filesystem is unmounted and remounted.
- 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 fsid or pmap 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. convert or create -srcdevice
- operations), while /dev/rdisk is usable for the quick pmap or fsid. 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).
- COMPATIBILITY
- 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 makehybrid) 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. flatten can be
- used to customize the type of metadata stored in the image.
- OS X 10.5 introduced sparse bundle images which compact quickly but are not recognized by previous OS
- versions. OS X 10.6 removed support for attaching SPARSEBUNDLE images from network file servers that
- don't support F_FULLFSYNC.
- HISTORY
- 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 hdiutil
- burn.
- WHAT'S NEW
- In OS X 10.6, pmap was rewritten to use MediaKit's latest reporting routines so that it can properly
- support GPT partition maps. Also -debug now implies -verbose for all verbs.
- OS X 10.5 changed the behavior of attach 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.
- SEE ALSO
- 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
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement
