# 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

pl |

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

Copyright © 2003 O'Reilly & Associates. All rights reserved.