source: trunk/appswitch/appswitch/appswitch.1@ 350

.Dd Tue Nov 6 2007       \" DATE 
.Dt APPSWITCH 1 LOCAL    \" Program name and manual section number 
.Os appswitch 1.1
.Sh NAME
.Nm appswitch
.Nd switch, hide, show, quit, kill or list Mac OS X applications
.Sh SYNOPSIS
.Nm appswitch
.Op Fl sShHqkKlLPfF      \" [-sShHqkKlLPfF]
.Op Fl c Ar creator      \" [-c creator]
.Op Fl i Ar bundleID     \" [-i bundleID]
.Op Fl a Ar name         \" [-a name]
.Op Fl p Ar pid          \" [-p pid]
.Op Ar path              \" [path]
.Sh DESCRIPTION
.Nm
controls the ordering and visibility of Mac OS X application windows.
.Nm
can also list or kill running applications.
.Ss Matching options
Matching identifies one or more applications to manipulate.
.Bl -tag -width -indent
.It Fl c Ar creator
Match by creator (a four-character code, also known as a signature).
.It Fl i Ar bundle ID
Match by bundle identifier, usually consisting of the reversed dot
(.)-separated components of the application developer's Internet domain
name, followed by the application name.  For example, the Finder's
bundle identifier is
.Ar com.apple.Finder .
Bundle identifiers are not case-sensitive.
.Pp
If you're extremely concerned about the speed of matching, any other
match method is faster than a match by bundle identifier.
.It Fl a Ar name
Match by application name.  This is not a recommended match criterion
as applications may be renamed at any time.
.It Fl p Ar pid
Match by process identifier (PID), a positive integer.
.It Ar path
Match by bundle path.  For packaged applications, this is the package
directory whose name typically has the .app extension, for example
.Ar /Applications/TextEdit.app
for the default installation location of TextEdit.  For non-packaged
applications, this is the path to the executable itself.
.El
.Ss Application actions
These actions apply to the matched application. If multiple
applications match the supplied criteria, only the first matching
application is acted upon.  The list option
.Fl l
displays all matching applications.
.Bl -tag -width -indent
.It Fl s
Show the application, making the application's windows frontmost.  Do
not switch to the application.
.It Fl h
Hide the application's windows.
.It Fl q
Quit the application.
.It Fl k
Kill (force quit) the application.  Sends the
.Dv SIGTERM
signal to the application, which the application may
ignore.  Equivalent to selecting 
.Dq Force Quit
from an application's menu in the Dock for the first time.
.It Fl K
Kill (force quit) the application.  Sends the
.Dv SIGKILL
signal to the application, which the application may not ignore.
Equivalent to selecting
.Dq Force Quit
from an application's menu in the Dock for the second time.
.It Fl l
List applications in a format similar to that of
.Xr ps 1 .
The columns of the listing are as follows:
.Bl -tag -width indent
.It PSN
The process serial number of the application.  Process serial numbers
are unique identifiers among both native Mac OS X and Classic
applications.
.It PID
The process identifier, a positive integer which uniquely identifies
native Mac OS X processes, usable with the
.Fl p
matching option.  Because all Classic applications run inside
TruBlueEnvironment, a single Mac OS X process, their process
identifiers appear as -1.
.It TYPE
The four-character code identifying the process's type, usually
.Ql APPL
for most applications or
.Ql FNDR
for the Finder.
Classic applications include additional types such as
.Ql appe
and
.Ql APPC
for applications which perform the functions of extensions and control
panels, respectively.  Depending on the Mac OS X version, non-packaged
applications may appear with no type or the type
.Ql ???? .
.It CREA
The four-character code identifying the application's creator, usable with the
.Fl c
matching option. Some Mac OS X applications have no creator, appearing
as 
.Ql ???? ;
for these applications you must use the bundle identifier,
name or path as match criteria.
.It NAME
The user-visible application name, usable with the
.Fl a
matching option. This field is truncated to 20 characters; the
remainder of longer application names is not displayed.
.It PATH
The path to the application bundle, or to the application executable
if the application is not packaged, usable with the
.Ar path
matching option. This field is truncated to the window width, or to 80
characters if the window width cannot be determined.
.El
.It Fl L
List applications in a format similar to that of
.Xr ps 1 .
The columns of the listing are as above, but the path field is not
truncated to the window width, and a bundle identifier is added in
parentheses after the path, usable with the
.Fl i
matching option.
.It Fl P
Print the application's process identifier (PID), a positive integer
and unique identifier for all applications except Classic
applications.
.It Fl f
Switch to the application, bringing only the frontmost window of the
application to the front.
.El
.Ss Actions
These actions affect all applications currently running.
.Bl -tag -width -indent
.It Fl S
Show all applications, layering the windows of initially hidden
applications on top.
.It Fl H
Hide windows of all applications other than the matched application,
or the frontmost application if no application has been matched.
.It Fl F
Order the current application's windows to the front.
.El
.Sh SEE ALSO 
.\" List links in ascending order by section, alphabetically within a section.
.\" Please do not reference files that do not exist without filing a bug report
.Xr open 1 ,
.Xr launch 1 ,
.Xr ps 1 ,
.Xr kill 1 ,
.Xr GetFileInfo 1
.Sh BUGS              \" Document known, unremedied bugs
The
.Fl S
option may not work in Mac OS X 10.5 with Spaces enabled.
.Sh AUTHOR
.An "Nicholas Riley" Aq appswitch@sabi.net
.\" .Sh HISTORY           \" Document history if command behaves in a unique manner