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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
 |  |  |
| A. The Mac OS X Filesystem |  | Index |
Copyright © 2003 O'Reilly & Associates. All rights reserved.