Appendix B. Command-Line Tools: The Missing Manpages

Unfortunately, many of the command-line utilities in Mac OS X have no corresponding manpages, and documentation on the utilities can be difficult to find, even with a Google search. This appendix offers a quick reference to tools that may be helpful or interesting to Mac OS X developers, but that lack manpages.

Each of the following sections includes the command syntax, a brief description, the directory location of the command, and the operating system with which it comes. Note that tools released with Darwin are also included in Mac OS X.

aexml

Syntax

aexml -soap -SOAPAction text [-in filename] [-out filename] [-name 'App 
Name' | -pid pid | psn highPSN.lowPSN | -sig signature]
aexml -xmlrpc [-in filename] [-out filename] [-name 'App Name' | -pid pid | 
psn highPSN.lowPSN | -sig signature]

Description

Translates SOAP and XML-RPC requests into Apple Events understood by Mac OS X applications. The target application can be specified by name, process ID, process serial number, or signature. If no target is specified, a sandbox application is launched to handle the request. Output, if any, is in the form of XML or a one-line error.

Options/Usage

-soap: Forwards a SOAP request to the target application.
-SOAPAction: Provides the SOAPAction header. If specified as -, the header is read from input.
-xmlrpc: Forwards an XML-RPC request to the target application.
-in: Specifies source of input. Defaults to - (standard input).
-out: Specifies location of output. Defaults to - (standard output).
-name: Specifies target application by pathname.
-pid: Specifies target application by Unix PID.
-psn: Specifies target application by Carbon Process Manager process serial number.
-sig: Specifies target application by signature. This is a four-character code unique to an application.The signature is usually the same as the application's creator code. In an application bundle, it is specified by the CFBundleSignature property in Info.plist.

Location

/usr/bin

Operating System

Mac OS X

configd

Syntax

config d [-b] [-B bundle_ID] [-d] [-t pathname] [-v] [-V bundle_ID]

Description

This is the System Configuration Server. configd is normally started as a daemon during the boot process. It monitors changes to network-related items, such as link status, DHCP assignments, PPP connections, and IP configuration, and provides an API for applications to be notified of these changes. To monitor various items, it uses a set of plug-in configuration agents, including the Preferences Monitor, the Kernel Event Monitor, the PPP Controller Agent, the IP Configuration Agent, and the IP Monitor Agent. The agent plug-ins are located in /System/Library/SystemConfiguration.

More information on the System Configuration framework can be found at http://developer.apple.com/techpubs/macosx/Networking/SysConfigOverview926/.

Options/Usage

-b: Disables loading of all agents.
-B: Disables loading of the specified agent.
-d: Disables daemonization; runs process in foreground.
-t: Loads the agent specified by pathname.
-v: Enables verbose logging.
-V: Enables verbose logging for the specified agent.

Location

/usr/sbin

Operating System

Darwin

DirectoryService

Syntax

DirectoryService [-h | -v]
DirectoryService [-appledebug | -appleframework | -applenodaemon | -
appleoptions | -appleperformance | -appleversion]

Description

This is the server process for the Directory Services framework.

Options/Usage

-h: Prints a usage statement for the first form of command invocation to standard output.
-v: Prints software release version to standard output.
-appledebug: Runs service in debug mode.
-appleframework: Starts service normally. This is the default.
-applenodaemon: Disables daemonization; runs service in foreground.
-appleoptions: Prints a usage statement for the second form of command invocation to standard output.
-appleperformance: Runs service in foreground and logs extensively.
-appleversion: Prints software build version to standard output.

Location

/usr/sbin

Operating System

Darwin

disktool

Syntax

disktool [-o | -r | -x | -y]
disktool [-d | -g | -m | -va | -vd | -vs] device
disktool [-e | -p | -s | -u] device integer_flag
disktool -n device vol_name
disktool -a device vol_name vol_flags

Description

Controls disks, including mounting, unmounting, ejecting, enabling permissions, and volume naming. Most options require a device name argument (for example, disk0), and some options require additional parameters.

Options/Usage

-a: Adds disk to Disk Arbitration tables, to notify applications of a mounted volume. This is useful if you have forced a mount, thus bypassing standard notification.
-d: Removes disk from Disk Arbitration tables, to notify applications of a dismount. This is useful if you have forced a dismount, thus bypassing standard notification.
-e: Ejects disk. Takes an additional argument that is normally set to 0.
-g: Gets HFS encoding on a volume.
-m: Mounts disk.
-n: Names volume.
-o: Opens vacant drive doors.
-p: Unmounts partition. Device name is that of a partition (for example, disk0s5). Takes an additional argument that is normally set to 0.
-r: Refreshes Disk Arbitration.
-s: Sets HFS encoding on a volume. Takes encoding as additional integer argument.
-u: Unmounts disk. Takes an additional argument that is normally set to 0.
-va: Adds device to /var/db/volinfo.database.
-vd: Deletes device from /var/db/volinfo.database.
-vs: Displays status of device in /var/db/volinfo.database.
-x: Disallows dismounts and ejects.
-y: Allows dismounts and ejects.

Location

/usr/sbin

Operating System

Darwin

dynamic_pager

Syntax

dynamic_pager [-F filename] [-H hire_point]  [-L layoff_point] [-P priority] 
[-S file_size]

Description

Manages virtual memory swap files. This tool is started from /etc/rc during the boot process.

Options/Usage

-F: Specifies the base absolute pathname for swap files. Swap filenames consist of this base and a whole number suffix, starting at 0. The default is /private/var/vm/swapfile.
-H: Creates an additional swap file when free swap space drops below the hire_point in bytes. The default is 0, which disables the use of this swap space.
-L: Attempts to consolidate memory and remove a swap file when free swap space rises above the layoff_point in bytes. The layoff_point must be set higher than the sum of the swap file size and the hire_point, unless it is set to 0 (the default), which disables layoffs.
-P: Determines the priority of this swap space. The default is 0.
-S: Determines the size of swap files created, in bytes. The default is 20000000.

Location

/sbin

Operating System

Darwin

ipconfig

Syntax

ipconfig getifaddr interface
ipconfig getoption { interface | "" } { option_name | option_code }
ipconfig getpacket interface
ipconfig ifcount
ipconfig set interface { BOOTP | DHCP }
ipconfig set interface { INFORM | MANUAL } IP_addr netmask
ipconfig waitall

Description

Interacts with the IP Configuration Agent of configd to manage network configuration changes.

Options/Usage

getifaddr: Prints the specified network interface's IP address to standard output.
getoption: Prints the value of the specified DHCP option to standard output. If interface is specified, the option is interface-specific. If empty quotes are used instead, the option is global. Option names and numeric codes are DHCP-standard (such as host_name, domain_name, netinfo_server_address, etc.).
getpacket: Prints DHCP transaction packets to standard output.
ifcount: Prints the number of network interfaces to standard output.
set: Sets the method by which the specified network interface is assigned an IP address. Using BOOTP or DHCP causes the system to attempt to contact a server of the appropriate type to obtain IP configuration information. Using INFORM sets the IP address locally, but initiates a DHCP request to obtain additional IP configuration information (DNS servers, default gateway, etc.). Using MANUAL indicates that all IP configuration information is set locally.
waitall: Sets the configurations of all network interfaces according to the specifications in /etc/iftab.

Location

/usr/sbin

Operating System

Darwin

opendiff

Syntax

opendiff file1 file2 [-ancestor ancestor_file] [-merge merge_file]

Description

Opens the two designated files in the FileMerge application.

Options/Usage

-ancestor: Compares the two files against a common ancestor file.
-merge: Merges the two files into a new file.

Location

/usr/bin

Operating System

Mac OS X

pbcopy

Syntax

pbcopy [-help]

Description

Copies standard input to the pasteboard buffer. The pasteboard is used to implement GUI copy, cut, and paste operations, drag-and-drop operations, and the Cocoa Services menu.

Options/Usage

-help: Prints an unhelpful usage statement to standard output.

Location

/usr/bin

Operating System

Mac OS X

pbpaste

Syntax

pbpaste[-help] [-Prefer { ascii | rtf | ps }]

Description

Prints the contents of the pasteboard to standard output. The combination of pbcopy and pbpaste may be an interesting tool to use in scripting. However, the system's global pasteboard can be modified by other processes at any time, which limits the tool's actual usefulness.

Options/Usage

-help: Prints a usage statement to standard output.
-Prefer: Specifies the output format to use if the desired format (ASCII, Rich Text Format, or PostScript) is available in the pasteboard.

Location

/usr/bin

Operating System

Mac OS X

Syntax

pl [-input input_binary_file | -output output_binary_file]

Description

Translates XML property list files into a more compact "key = value" format. Also translates between this and a serialized binary format, in either direction. XML is read from standard input, "key = value" data is read from standard input and written to standard output, and serialized binary data is read from and written to files specified with arguments.

Options/Usage

-input: Specifies a serialized binary file as input.
-output: Specifies a serialized binary file as output.

Examples

cat foo.plist | pl: Translates XML property list to "key = value" format.
cat foo.plist | pl | pl -output foo.bin: Translates XML property list to serialized binary format.
pl -input foo.bin: Translates serialized binary file to "key = value" format.

Location

/usr/bin

Operating System

Mac OS X

scselect

Syntax

scselect [[-n] location]

Description

Changes active network location, similar to selecting a network Location from the Apple menu. If there are no arguments, a usage statement and a list of defined Locations (or "sets") as defined in the Network System Preferences panel is printed to standard output, along with an indication of which location is currently active. Locations can be referred to by name or by integer ID.

Options/Usage

-n: Changes the active network Location, but does not apply the change.

Location

/usr/sbin

Operating System

Darwin

scutil

Syntax

scutil [-r node_or_address | -w key [-t timeout]]

Description

Provides control of the System Configuration framework's dynamic store. scutil opens an interactive session with configd, in which various commands are available to view and modify System Configuration keys.

As a quick sample run-through, invoke scutil. You will be placed at the scutil prompt. Enter open to start the session with configd, then enter list. You will see a set of keys, some of which are provided by the System Configuration framework (such as the keys in the File: domain), some of which are obtained from the preferences file /var/db/SystemConfiguration.xml (the Setup: keys), and some of which are published by the configuration agents (the State: keys). Enter get State:/Network/Global/DNS to load the dictionary associated with that key. Then run d.show to display it. You should see a list of DNS servers and search domains configured on your system. Finally, run close, then quit.

Options/Usage

-r: Checks for reachability of the node or address. (Any numerical argument seems to result in Reachable status.)
-t: Specifies the timeout to wait for the presence of a data store key, in seconds. The default is 15.
-w: Exits when the specified key exists in the data store or when the timeout has expired.

Commands

scutil enters interactive mode when it is invoked with no arguments.

add key [temporary]: Adds a key to the data store with the value of the current dictionary. The temporary keyword causes it to be flushed when the session to configd is closed.
close: Closes a session with configd.
d.add key [* | ? | #] value...: Adds an entry to the current dictionary. The optional type specifier can designate the values as arrays (*), booleans (?), or numbers (#).
d.init: Creates an empty dictionary.
d.remove key: Removes the specified key from the current dictionary.
d.show: Displays the contents of the current dictionary.
f.read file: Reads prepared commands from a file.
get key: Causes the value of the specified key to become the current dictionary.
help: Prints a list of available commands.
list [key_pattern]: Lists keys in the System Configuration data store. The key_pattern can restrict which keys are output, but key_pattern appears to be quite limited.
n.add { key | key_pattern }: Requests notification of changes to the specified keys.
n.cancel: Cancels n.watch settings.
n.changes: Lists changed keys that have been marked with notification requests.
n.list [key_pattern]: Lists keys upon which notification requests have been set.
n.remove { key | key_pattern }: Removes notification requests for the specified keys.
n.watch [verbose]: Causes changes to keys marked with notification requests to issue immediate notices, obviating the need to use n.changes to serve notice that the change has occurred.
notify key: Sends a notification for the specified key.
open: Opens a session with configd.
quit: Exits the scutil session.
remove key: Removes the specified key from the data store.
set key: Sets the specified key to the value of the current dictionary.

Location

/usr/sbin

Operating System

Darwin

SplitForks

Syntax

SplitForks { -u | [-v] pathname }

Description

Splits the resource fork out of a dual-forked file into a file named ._pathname. You can also do this with cp pathname/..namedfork/rsrc ._pathname. This method results in a resource file amenable to processing by DeRez, whereas the output of SplitForks does not appear to produce a file that DeRez can understand.

Options/Usage

-u: Prints a usage statement to standard output.
-v: Enables verbose output.

Location

/Developer/Tools

Operating System

Mac OS X

tiff2icns

Syntax

tiff2icns [-noLarge] input_filename [output_filename]

Description

Converts TIFF image files to Apple icon (ICNS) files. If output_filename is not specified, the output file receives the same name as the input file, with the filename extension changed to .icns.

Options/Usage

-noLarge: Prevents the creation of the highest resolution icons.

Location

/usr/bin

Operating System

Mac OS X

tiffutil

Syntax

tiffutil { -dump | -info | -verboseinfo } input_file...
tiffutil { -extract  number | -jpeg [-fN] | -lzw | -none | -packbits } 
input_file [-out output_file]
tiffutil -cat input_file... [-out output_file]

Description

Manipulates TIFF image files.

Options/Usage

-cat: Concatenates multiple input files.
-dump: Prints a list of all tags in the input file to standard output.
-extract: Extracts an individual image from the input file, with 0 designating the first image in the file.
-f: Specifies the compression factor to use with JPEG compression. The value can range from 1 to 255. The default is 10.
-info: Prints information about images in the input file to standard output.
-jpeg: Specifies the use of JPEG compression when producing the output file.
-lzw: Specifies the use of Lempel-Ziv-Welch compression when producing the output file.
-none: Specifies the use of no compression when producing the output file.
-output: Specifies the name of the output file; defaults to out.tiff.
-packbits: Specifies the use of PackBits compression when producing the output file.
-verboseinfo: Prints lots of information about images in the input file to standard output.

Location

/usr/bin

Operating System

Mac OS X

udf.util

Syntax

udf.util -m device mount_point
udf.util { -p | -u } device

Description

Mounts UDF (DVD) filesystems into the directory hierarchy.

Options/Usage

-m: Mounts the device.
-p: Probes the device for mounting.
-u: Unmounts the device.
device: Specifies the DVD device filename, for example, disk1.
mount_point: Specifies the directory on which the DVD filesystem will be mounted.

Location

/System/Library/Filesystems/udf.fs

Operating System

Darwin

vsdbutil

Syntax

vsdbutil { -a | -c | -d } pathname
vsdbutil -i

Description

Enables or disables the use of permissions on a disk volume. This is equivalent to using the Ignore Privileges checkbox in the Finder's Info window for a mounted volume. The status of permissions usage on mounted volumes is stored in the permissions database, /var/db/volinfo.database.

Options/Usage

-a: Activates permissions on the volume designated by pathname.
-c: Checks the status of permissions usage on the volume designated by pathname.
-d: Deactivates permissions on the volume designated by pathname.
-i: Initializes the permissions database to include all mounted HFS and HFS+ volumes.

Location

/usr/sbin

Operating System

Darwin