This article contains release notes for the the Mac OS X Server release of the Terminal application.

Note: This document was installed by Mac OS X Server in /System/Documentation/ReadMe. For a list of other release notes see: Tech Info Library Article 30925: " Mac OS X Server: Release Notes "

For those familiar with Terminal in OpenStep for Mach, notes specific to this release are included. Also, a section is devoted to some of Terminal's less obvious features. Finally, this document includes information about Terminal's execution service, which is of interest mainly to developers.

New Features

The following new features have been added to the Terminal application in this release.

* Terminal has been moved to the directory /System/Administration (it used to live in /NextApps ).

/usr/bin/defaults write Terminal LibraryMenu YES
After restarting Terminal, the Shell>Library menu contains an item for each of the abovementioned files.

These new bugs have appeared since OpenStep for Mach 4.2.

* Saved Windows : You can save a window or set of windows to a file, thereby saving your preferred configurations. Everything about the windows is saved except the contents of the scrollback buffer; this includes the shell, the location of the window, and whether the window is miniaturized. When you choose the Save As command, you can decide whether all windows or just the main window is saved.

Once a window is associated with a file, Save can be used to flush the settings out without seeing a Save Panel, just as with more conventional documents. However, if more than one window belongs with that file, all the relevant windows will be re-saved (the Save menu item indicates this by changing its label to Save Set). This convention allows you to open a set of windows, rearrange them, and type Command-s to save them back to the file.

To have a file opened for you automatically each time you start up Terminal, you can either check a box in the Save As panel, or you can specify the filename in the Preferences panel under Startup options.

To make this evaluation, Terminal collects ps -type information about processes it considers relevant and applies a number of heuristics. Usually, Terminal considers shells and a few other garden-variety processes such as su to be innocuous and will not mark windows busy on their account. But there are exceptions; for example, if the distinguished process on the tty is a shell but it is actively running, the window will be dirty. You may designate additional "clean" command names ( rlogin and telnet are common) in the preferences panel. If there are running processes on the terminal, the terminal might still be clean if the processes seem to be running in the background. But an interesting process that's the current process or that you've explicitly suspended with Control-z will always make the window dirty.

The status of windows is checked only when it is likely to have changed. A back-off strategy prevents the probes from happening too often if the window seems constantly busy.

Quick Title provides the current title of the window for you to edit; however, when you set the title this way Terminal won't update any of the information in the future. For example, if your window is titled "/bin/csh 80x24 ~/Term.term" and you edit that to include some text of your own choosing, the new title is treated as a string and won't reflect (for example) the size of the window should you change it. The preferences panel allows better control over this; you can mix your own material with Terminal's automatically updated information.

New Command does use path searching when it execs your command, but since the path is just the default inherited from Workspace, it's utility is limited. You can add arguments, but shell metacharacters won't be handled correctly.

ESC ] 0 ; "Title String" BEL

where ESC is '\033', and BEL is '\007'. The initial 0 may alternatively be a 2. The following csh script code (which can be added to a .cshrc file) shows one example of how you can set the title bar to a "clipped" version of the current directory. It also puts the hostname in the prompt in inverse video:



# begin csh script to set the title bar to the current working directory
set homedirectory = ~${user}
alias shortpwd 'pwd|sed -e "s|^/private||" -e "s|${homedirectory}|~${user}|"'
alias getTitle 'set titleString="`shortpwd|sed -e '\''s|.*[^/]\(/[^/]*/[^/]*/[^/]*/[^/]*\)|...\1|'\'' `"'
getTitle

if( ${?prompt} ) then
set hostNm=`hostname`
alias cd 'cd \!*; getTitle ; echo -n "*]0;${titleString}*" ; set prompt = "*[7m${hostNm} >*[m "'
endif
cd .
#end csh script

When you specify the command associated with a service, you can use the tokens "%s" and "%p" to refer to the location where the selection and prompted input are inserted, respectively (prompted input is not requested unless this string appears in the command).

TERM_PROGRAM=Apple_Terminal
TERM_PROGRAM_VERSION=99.99  (or something else...)

Terminal's Execution Service

Overview

The TSTerminalDOServices protocol, declared in the header /System/Developer/Headers/Apps/TerminalDOProtocol.h , allows applications to request that the Terminal application perform commands on their behalf. This is useful if a program wants to open up a shell window for the user to interact with, and it may be easier than setting up pipes and doing a fork / exec of a program yourself.

Terminal cannot provide services if it is not running. It may be necessary to use the Application Kit's NSWorkspace API to launch Terminal if the connection to Terminal fails.

You may run the commands in a window, in which case an integer window handle is returned to allow a window to be reused for subsequent commands, or the commands can performed in the background. In addition, you can specify the window's title, as well as the working directory and environment to be used when executing the command.

In the case of commands performed in the background only, you can pass in an NSData object whose data will be fed to the command's standard input, and if you pass in a pointer to an NSData, Terminal can hand you back the output of the command's standard output and standard error. If you pass a pointer to get these back, the data at the pointer should be nil before you invoke the command. Upon completion, the pointer points to an newly created NSData containing the output.

For details on the specific methods in the protocol, see the header file referenced above.

Security Considerations

By default, Terminal registers a port for the execution service with the Mach bootstrap server. This means that only processes descended from the Workspace application have access to this service. You can also have Terminal register this port with the Mach netname server, which allows access from other machines on the network. This is enabled by setting the default

/usr/bin/defaults write Terminal PublicDOServices YES

Important Note

Running with this default is a security hazard , as Terminal has no way of verifying who is making the remote connection.

Disabling the Service

Any user may disable this service by executing the following command:

/usr/bin/defaults write Terminal DisableDOServices YES

The superuser can disable it for all users on a given machine by giving this command:

touch /System/Administration/Terminal.app/.DisableDOServices

Sample Code and Client

The program /usr/bin/terminal , mentioned above in "A Tool for Creating New Terminal Windows," is a simple client which utilizes this protocol. The following is the source code for this program:

//
//  terminal.m
//
//        Sample client for Terminal.app's Distributed Objects services.
//        Copyright 1994-1997, Apple Computer, Inc. All rights reserved.
//
//
//    This program opens a terminal window in the current directory. It's installed
//    in /usr/bin/terminal.
//
//    Author: sam streeper
//    Updated by: Barry Locklear, Grant Baillie
//
//    To compile:
//
//      cc terminal.m -I/System/Developer/Headers -framework Foundation -o terminal
//
//    Usage:
// terminal [-shell] [-dir <dir>] [-noclose] [-env] [command]
//

#import <AppKit/AppKit.h>
#import <Foundation/Foundation.h>
#import <stdio.h>
#import <mach/mach.h>
#import <servers/bootstrap.h>
#import <Apps/TerminalDOProtocol.h>

static void usage(void) {
fprintf(stderr,"terminal: open a new Terminal.app window\n\n");
fprintf(stderr,"Usage: terminal [-shell] [-dir <dir>] [-noclose] [-env] [command]\n");
fprintf(stderr," -shell   - Run command from default shell\n");
fprintf(stderr," -dir     - Specify working directory (default is current)\n");
fprintf(stderr," -noclose - Retain window upon exit\n");
fprintf(stderr," -env     - Export current environment\n");
exit(-1);
}

static id<TSTerminalDOServices> lookupTerminalDOServer(void) {
port_t sendMachPort;
NSDistantObject *rootProxy = nil;
id<TSTerminalDOServices> result;

// First, try look up Terminal's DO object in the bootstrap server.
// This is where the app registers it by default.
if ((BOOTSTRAP_SUCCESS == bootstrap_look_up(bootstrap_port, "TerminalDO", &sendMachPort)) && (PORT_NULL != sendMachPort)) {
NSConnection *conn = [NSConnection connectionWithReceivePort:[NSPort port] sendPort:[NSPort portWithMachPort:sendMachPort]];
rootProxy = [conn rootProxy];
}

// If the previous call failed, the following might succeed if the user
// logged in is running Terminal with the PublicDOServices user default
// set.
if (!rootProxy) {
rootProxy = [NSConnection rootProxyForConnectionWithRegisteredName:@"TerminalDO" host:@""];
}

// We could also try to launch Terminal at this point, using
// the NSWorkspace protocol.
if (!rootProxy) {
fprintf(stderr,"Can't connect to Terminal\n");
exit(-1);
}

[rootProxy setProtocolForProxy:@protocol(TSTerminalDOServices)];
result = (id<TSTerminalDOServices>)rootProxy;

if ([result protocolVersion] < 0x10002) {
fprintf(stderr,"Incompatible terminal protocol version\n");
exit(-4);
}

return result;
}

int main(void) {
NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
id <TSTerminalDOServices> terminal = lookupTerminalDOServer();

NSEnumerator *argsEnum = [[[NSProcessInfo processInfo] arguments] objectEnumerator];
NSString *thisArg;

int returnCode;
NSMutableString *command = nil;
NSDictionary *environment = nil;
NSString *directory = nil;
TSShellType shellType = TSShellNone;
TSExitAction exitAction = TSCloseUnlessError;

int winHandle;

NSData *inputData = nil;
NSData *outputData = nil;
NSData *errorData = nil;


thisArg = [argsEnum nextObject]; /* Skip the program name */

if (nil == thisArg) {
shellType = TSShellDefault;
}

// Run through the command-line arguments. We only set command to
// something non-nil once we encounter an argument that isn't an
// option. Once we've done this, though, we treat the rest of
// the arguments as part of the command.
//
while(thisArg = [argsEnum nextObject]) {
if (command) {
[command appendFormat:@" %@", thisArg];
}
else if (![thisArg hasPrefix:@"-"]) {
command = [[thisArg mutableCopy] autorelease];
}
else  if ([@"-shell" isEqualToString:thisArg]) {
shellType = TSShellDefault;
}
else if ([@"-dir" isEqualToString:thisArg]) {
if (!(thisArg = [argsEnum nextObject])) usage();
directory = thisArg;
}
else if ([@"-noclose" isEqualToString:thisArg]) {
exitAction = TSDontCloseOnExit;
}
else if ([@"-env" isEqualToString:thisArg]) {
environment = [[NSProcessInfo processInfo] environment];
}
else {
usage();
}
}

if (!directory) directory = [[NSFileManager defaultManager] currentDirectoryPath];
if (!command) command = [NSMutableString stringWithCString:""];

[terminal runCommand:command
inputData:inputData
outputData:&outputData
errorData:&errorData
waitForReturn:NO
windowType:TSWindowNew
windowHandle:&winHandle
exitAction:exitAction
shellType:shellType
windowTitle:command
directory:directory
environment:environment
returnCode:&returnCode];

[pool release];

exit(returnCode);
}