tether 0.0.1
Loading...
Searching...
No Matches
libtether.h File Reference

Public interface of libtether: attach and detach macOS disk images. More...

#include <CoreFoundation/CoreFoundation.h>
#include <stdbool.h>
Include dependency graph for libtether.h:

Go to the source code of this file.

Classes

struct  teth_attach_options
 Options controlling how teth_attach() mounts an image. More...

Macros

#define LIBTETHER_VERSION   "0.0.1"
 libtether version string (semver).

Functions

int teth_attach (const char *image_path, const teth_attach_options *opts, CFDictionaryRef *out_results)
 Attach (mount) the disk image at image_path.
void teth_print_attach_results (CFDictionaryRef results)
 Print the system-entities of an attach result to stdout.
int teth_detach (const char *dev_or_mount, bool force, double timeout_seconds)
 Detach (unmount and eject) a previously attached image.

Detailed Description

Public interface of libtether: attach and detach macOS disk images.

libtether tethers a disk image to the running system: attach mounts it as a /dev/diskN device, and detach unmounts and releases it again. It does only those two things — there is no creation or format manipulation. It replicates what hdiutil attach and hdiutil detach do:

  • attach uses the private DiskImages.framework (DIHLDiskImageAttach);
  • detach uses the public DiskArbitration.framework (unmount and eject of the whole disk), mirroring hdiutil's unmount_and_eject path.

Function Documentation

◆ teth_attach()

int teth_attach ( const char * image_path,
const teth_attach_options * opts,
CFDictionaryRef * out_results )

Attach (mount) the disk image at image_path.

Builds the DiskImages option dictionary exactly as hdiutil attach does and calls DIHLDiskImageAttach. Works for any image format DiskImages recognises (UDIF .dmg, .sparseimage, .sparsebundle, .iso/.cdr, NDIF, encrypted), not just .dmg.

Parameters
image_pathFilesystem path to the disk image. May be a regular file or, for a .sparsebundle, a directory.
optsAttach options, or NULL for the defaults (read-only, verified).
[out]out_resultsIf non-NULL, receives a retained CFDictionaryRef on success: the attach result whose system-entities key is a CFArray of {dev-entry, mount-point, content-hint} dictionaries. The caller takes ownership and must release it with CFRelease().
Returns
0 on success; a non-zero DiskImages status code on attach failure; or a negative value for local errors (-2 invalid path, -3 DiskImages framework load failure).
Note
On success the DiskImages framework is left loaded for the lifetime of the process so that the attached device outlives this call.
See also
teth_detach(), teth_print_attach_results()

◆ teth_detach()

int teth_detach ( const char * dev_or_mount,
bool force,
double timeout_seconds )

Detach (unmount and eject) a previously attached image.

Resolves dev_or_mount to its whole disk, then performs a whole-disk DADiskUnmount followed by DADiskEject through DiskArbitration, mirroring hdiutil's unmount_and_eject. Operating on the whole disk tears the image down, equivalent to hdiutil detach.

Parameters
dev_or_mountTarget as a BSD device name (disk4), a /dev path (/dev/disk4, /dev/disk4s1, /dev/rdisk4s1), or a mount point (/Volumes/Foo). A partition spec still detaches the whole disk.
forceIf true, add the force option to the unmount.
timeout_secondsUpper bound, in seconds, on the wait for each DiskArbitration callback; a value <= 0 selects a sane default.
Returns
0 on success; a non-zero DADissenter status on unmount/eject failure; or a negative value for local errors (-2 unparseable target, -3 DiskArbitration session-create failure).
See also
teth_attach()

◆ teth_print_attach_results()

void teth_print_attach_results ( CFDictionaryRef results)

Print the system-entities of an attach result to stdout.

Writes one line per entity formatted as <dev-entry>\t<content-hint>\t<mount-point>, matching the spirit of hdiutil attach output. Entities without a mount point (for example a whole-disk partition scheme) print an empty mount-point field.

Parameters
resultsAn attach result dictionary as produced by teth_attach(). Passing NULL is a no-op.
See also
teth_attach()