This is MiscSubprocess.rtf in view mode; [Download] [Up]
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:asynchronously: execute:withPtys: execute:withPtys:asynchronously: - 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: 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: - 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: - 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.
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.