Release 1.2 Copyright ©1994 by Don Yacktman. All Rights Reserved.
MiscSubprocess |
Inherits From: | Object | |
Declared In: | <misckit/MiscSubprocess.h> |
Class Description |
No Description. Please, if anyone has the time, help us finish any missing docs you find! |
Instance Variables |
id delegate; id environment; FILE *fpToChild; FILE *fpFromChild; int stdoutFromChild; int stderrFromChild; int childPid; id stdoutBuffer; id stderrBuffer; BOOL paused; BOOL running; BOOL usePtys; BOOL asynchronous; |
delegate | MiscSubprocess' delegate object. | |
environment | MiscStringArray that holds the child's environment. | |
fpToChild | Pipe for sending data to the child process' stdin. | |
fpFromChild | Pipe for receiving data from the child process' stdout. | |
stdoutFromChild | File descriptor of pipe for receiving data from the child process' stdout. | |
stderrFromChild | File descriptor of pipe for receiving data from the child process' stderr. | |
childPid | PID of the child process. | |
stdoutBuffer | MiscString used to buffer the child's stdout. | |
stderrBuffer | MiscString used to buffer the child's stderr. | |
paused | True if child process is paused. | |
running | True if the child process is running. | |
usePtys | True if pty support should be used by degenerate execute: methods. | |
asynchronous | True if degenerate execute: methods should run an asynchronous subprocess. |
Method Types |
Initializing a MiscSubProcess: | - init - init: - init:asynchronously: - init:keepEnvironment: - init:keepEnvironment:asynchronously: - init:keepEnvironment:withPtys: - init:keepEnvironment:withPtys:asynchronously: - init:withDelegate: - init:withDelegate:keepEnvironment: - init:withDelegate:keepEnvironment:asynchronously: - init:withDelegate:keepEnvironment:withPtys: - init:withDelegate:keepEnvironment:withPtys:asynchronously: - init:withDelegate:asynchronously: - init:withDelegate:withPtys: - init:withDelegate:withPtys:asynchronously: - init:withPtys: - init:withPtys:asynchronously: | |
Sending Data to Child: | - send: - send:withNewline: - terminateInput | |
Sending Data From Child to Delegate: | - flushBuffer: - flushBuffer:as: - outputMethodForBuffer: | |
Obtaining Information About Child: | - environment - isPaused - isRunning - pid | |
Controlling Child Process: | - execChild: - execute: - execute:asynchronously: - execute:withPtys: - execute:withPtys:asynchronously: - pause: - resume: - terminate: | |
Delegate methods: | - delegate - setDelegate: - subprocess:done:: - subprocess:error: - subprocess:output: - subprocess:stderrOutput: |
Instance Methods |
delegate |
- delegate |
Returns the MiscSubprocess' delegate object, the object responsible for handling errors and receiving output from the
child process.
See also: -setDelegate: and the delegate methods at the end of this document.
environment |
- environment |
Returns a MiscStringArray object that contains the environment that will be set up for the child process when it is
started. If you wish to alter the environment, add to or modify the MiscStringArray returned by this method. Under no
circumstances should you free the object returned to you; it is owned by the MiscSubprocess instance.
See also: - execute:withPtys:asynchronously:
execChild: |
- execChild:(const char *)aString |
This is used internally by MiscSubprocess to actually start the child process, using the UNIX execle(). If you wish to
override how a child process is started, you should override this method and not -execute:.
See also: -environment and -execute:withPtys:asynchronously:
execute: |
- execute:(const char *)aString withPtys:(BOOL)ptyFlag asynchronously:(BOOL)async |
Sets up pipes to a child process and starts it executing the command in aString using ptys if ptyFlag is equal to YES. If
async is NO then this method will not return until the process finishes running. The ptyFlag parameter turns PTY
support on and off. Returns self. The degenerate methods use the instance variables usePtys for ptyFlag and
asynchronous for async.
See also: -environment, -execChild:, -pause:, -resume:, and -terminate:
flushBuffer: |
- flushBuffer:aString |
Flushes the buffer aString to the delegate. This is used internally by MiscSubprocess to send the stdin and stdout of the
child process to the delegate.
See also: -flushBuffer:as:, -outputMethodForBuffer:
flushBuffer:as: |
- flushBuffer:aString |
as:aBuffer |
This method is used internally by the MiscSubprocess object to flush the stderr and stdout buffers of the child process.
The string value of aString will be passed on to the delegate via the -subprocess:output: or
-subprocess:stderrOutput: delegate methods. This method could be used to spoof data as if it came from the child
process. Returns self.
See also: -flushBuffer:, -outputMethodForBuffer:
init |
- init |
Initializes a new instance of MiscSubprocess. The environment is initialized to be a copy of the current environment,
and no delegate is assigned. No process is run initially. Returns self.
See also: -init: and -init:withDelegate:
init |
- init:(const char *)aString |
withDelegate:theDelegate keepEnvironment:(BOOL)flag withPtys:(BOOL)ptyFlag asynchronously:(BOOL)async |
This is the designated initializer for the MiscSubProcess class. Initializes a new instance of MiscSubprocess and runs
the command in aString with theDelegate as the delegate object. If aString is NULL, then no command is run; the
instance variables should be set up later as required and then -execute: should be called foranything to happen. If flag
is YES, then the environment is initialized to be a copy of the current environment. If flag is NO, then the environment
starts out empty, which could cause strange things to happen unless you know exactly what you are doing. Use
-environment to access and modify the MiscStringArray which contains the environment used by the
MiscSubprocess. The parameters ptyFlag and async are used to set up the instance variables usePtys and
asynchronous, respectively. (They are used by the degenerate execute: methods.) Returns self. In the degenerate
methods, aString defaults to NULL, theDelegate defaults to nil, flag defaults to YES, ptyFlag defaults to NO, and
async defaults to YES.
See also: - execute:withPtys:asynchronously:, -init, and -init:
isPaused |
- (BOOL)isPaused |
Returns YES is the child process is paused. Returns NO otherwise.
See also: -isRunning, -pause:, and -resume:
isRunning |
- (BOOL)isRunning |
Returns YES if the child process is running, NO otherwise.
See also: -isPaused, -pause:, and -resume:
outputMethodForBuffer: |
- (SEL)outputMethodForBuffer:aBuffer |
Used internally by the MiscSubprocess object to determine which delegate method to send for aBuffer. It will return
the selector for either -subprocess:output: or -subprocess:stderrOutput: depending on whether the argument is the
buffer being used for stderr or stdout of the child process. Returns NULL if the argument is some other buffer.
See also: -flushBuffer: and -flushBuffer:as:
pause: |
- pause:sender |
Pause the child process by sending it a SIGSTOP signal. Returns self.
See also: -isPaused, -isRunning, -resume:, and -terminate:
pid |
- (int)pid |
Returns the process ID (pid) of the child process, if it exists. If there is no child process running, the return value is
undefined and invalid.
resume: |
- resume:sender |
Resumes a paused child process by sending a SIGCONT signal. Returns self.
See also: -isPaused, -isRunning, -pause:, and -terminate:
send: |
- send:(const char *)string |
Sends string, followed by a newline character (`\n') to the child process. Returns self.
See also: -send:withNewLine: and -terminateInput
send:withNewline: |
- send:(const char *)string |
withNewline:(BOOL)wantNewline |
Sends string to the child process. If wantNewLine is true, then a newline character (`\n') is appended to string.
Returns self.
See also: -send: and -terminateInput
setDelegate: |
- setDelegate:anObject |
Sets the delegate object. See the delegate methods below for a description of what information is sent to the delegate.
Returns self.
See also: -delegate
setExecArgs::: |
- setExecArgs:(const char *)a0 :(const char *)a1 :(const char *)a2 |
Changes the command that will be used to run the child process. This allows you to choose the shell to execute the
child, for example. The path to the shell should be in a0. The values of a1 and a2 will be used as argv[0] and argv[1],
respectively. The default arguments are "/bin/sh", "sh", "-c". Returns self.
See also: -delegate
- setExecArgs:(const char *)a0 :(const char *)a1 :(const char *)a2; |
- terminate:sender |
Sends a SIGKILL to the child process, terminating it's execution. Returns self.
See also: -pause:, -resume:, and -terminate:
terminateInput |
- terminateInput |
Terminate the data being sent to the child process. This will send an EOF to the child's stdin. Returns self.
See also: -send: and -send:withNewLine: |
Delegate Methods |
subprocess:done:: |
- subprocess:sender done:(int)status :(MiscSubprocessEndCode)code |
Sent to the delegate when the child process completes. The exit code code is the reason for the process' termination,
and is one of Misc_Exited, Misc_Stopped, Misc_Signaled, or Misc_UnknownEndCode. If the process exited normally,
the exit code is returned in status. If the process was stopped, then status contains the number of the signal that caused
the process to stop. If the process was signaled, then status contains the number of the signal that caused the process
to terminate.
subprocess:output: |
- subprocess:sender output:(const char *)buffer |
Sent whenever there is data on the process' standard output pipe. The data is passed in buffer and is only valid until the
next method call and should therefore be cached locally if need be.
See also: -subprocess:stderrOutput:
subprocess:stderrOutput: |
- subprocess:sender stderrOutput:(const char *)buffer |
Sent whenever there is data on the process' standard output pipe. The data is passed in buffer and is only valid until the
next method call and should therefore be cached locally if need be.
See also: -subprocess:output:
subprocess:error: |
- subprocess:sender error:(const char *)errorString |
Sent if an error occurs when dealing with the child process. Most errors will occur when trying to start the process. By default, this method is a part of a category of the object class which simply passes errorString to perror(). Override this method if you wish to attempt error recovery or present the error to the user somewhere besides the console. |