Process Management Primitives
| Process Management Primitives | |
| Macros | |
| connect | Attach a process to a process. |
| disconnect | Disconnect a buffer from a process. |
| dos | Create a sub-shell. |
| inq_connection | Connection information. |
| insert_process | Send string to a attached process. |
| perror | Print error. |
| send_signal | Send signal to a process buffer. |
| shell | Spawn a sub-shell process. |
| sleep | Suspend execution for an interval of time. |
| strerror | String error. |
| strsignal | Return string describing signal. |
| suspend | Suspend current process. |
| wait | Wait for attached process to terminate. |
| wait_for | Wait for process output. |
| Signals | Signals are a limited form of inter-process communication used in Unix, Unix-like, and other POSIX compliant operating systems. |
connect
int connect( int mode, string shell = NULL, string cwd = NULL )
Attach a process to a process.
Description
The connect() primitive creates a sub-process and attaches it to the current buffer. The buffer behaviour is similar to that of a virtual terminal with the sub-process standard input and output streams redirected to the buffer. The virtual terminal implementation is system dependent yet most utilise pseudo-devices otherwise pipes.
All text inserted into the buffer is automatically forwarded to the underlying sub-process, insertion methods include self_insert, insert and paste. In addition the primitive insert_process allows for explicit text to be forwarded without echo.
Likewise output from the underlying sub-process is sent to the buffer. All output from the sub-process is automatically inserted into the buffer, at the process insertion position; see inq_process_position and set_process_position.
The mode argument specifies the control flags the behaviour of the connection, if omitted defaults to PF_ECHO.
By default, the process created is a shell process, and the shell is got from the SHELL environment variable. If shell is specified, then it is taken as the pathname of a shell to execute.
Once attached connect() may be called to change the mode flag.
Modes
Control flags
| Constant |
Value |
Description |
|---|---|---|
| PF_ECHO |
0x0001 |
Reserved for macro use, denotes all typed key strokes are redirected to the process using a REG_TYPE signal handler (See: register_macro). |
| PF_NOINSERT |
0x0002 |
Reserved for macro compatibility, disables automatic insertion of sub-process output into the associated buffer; not implemented. |
| PF_NONINTERACTIVE |
0x0004 |
Non-interactive mode command shell. |
| PF_LOCALECHO |
0x1000 |
Local echo mode, characters written to the buffer using either insert or self_insert shall be automatically sent to the process. |
| PF_OVERWRITE |
0x4000 |
Overwrite process input (CR/LF conversion). Indicates whether output from a process overwrites text in the buffer or inserts and shifts text over as it does so. Needed for effectively allow type-ahead to not be destroyed but allow escape sequences to cause data in the buffer to be overwritten when running termcap oriented programs. |
| PF_WAITING |
0x8000 |
Waiting for text. Normally when a buffer is created, the output from the subprocess is inserted directly into the buffer. Setting this bit causes the output from the process to be held onto, until the calling macro issues a wait or wait_for. |
Parameters
| mode | Optional integer control flags. |
| shell | Optional string containing the SHELL specification is be utilised, if omitted the environment value of SHELL is used. |
| cwd | Optional string containing current working directory. |
Returns
The connect() primitive returns the positive IP identifier associated identifier with the created connection, 0 if the buffer is already connected, otherwise -1 on error.
Portability
n/a
See Also
insert_process, inq_connection, disconnect, wait, shell, dos
disconnect
int disconnect()
Disconnect a buffer from a process.
Description
The disconnect() primitive disconnects the current buffer from any attached process, if any, terminating the subprocess.
Note:
Under Unix the terminated subprocess is sent a SIGTERM followed by a SIGKILL signal.
Parameters
none
Returns
Returns 1 on success otherwise 0.
Portability
n/a
See Also
dos
int dos( [string cmd], [int use_shell], [string callback] )
Create a sub-shell.
Description
The dos() primitive executes the specified command cmd, if omitted starts an interactive command shell.
This function is provided for compatibility using the shell interface; see the shell and the brief macro module for details.
Parameters
| cmd | String containing the command to be executed. |
| shell | Optional integer stating whether a shell should be utilised, if non-zero use of a shell shall be omitted if feasible. |
| callback | Optional string containing the name of a macro to be executed on the completion of the task. If stated the command is intended to run as a background task, otherwise in the foreground. |
Returns
The dos() primitive returns the completion value of the corresponding command.
A negative value denotes an execution failure; on failure errno contains a value indicating the type of error that has been detected including.
| Constant |
Description |
|---|---|
| E2BIG |
Combined Size of environment and argument list is too large. |
| EACCES |
Search permission is denied on a component of the path prefix of filename or the name of a script interpreter. |
| EACCES |
The file or a script interpreter is not a regular file. |
| EACCES |
Execute permission is denied. |
| EIO |
An I/O error occurred. |
| ENAMETOOLONG |
Path is too long. |
| ENOENT |
The command or one of its components does not exist. |
| ENOEXEC |
An executable is not in a recognized format, is for the wrong architecture, or has some other format error that means it cannot be executed. |
| ENOMEM |
Insufficient kernel memory was available. |
Portability
n/a
See Also
inq_connection
int inq_connection( int cid, int & flags, int & pid )
Connection information.
Description
The inq_connection() primitive retrieves information regarding the connection cid.
Parameters
| cid | Integer connection identifier returned from connect. |
| flags | Integer variable to be populated with the connection flags. |
| pid | Integer variable to be populated with the connection process identifier. |
Returns
nothing
Portability
A GriefEdit extension.
See Also
insert_process
int insert_process( string|int val, [int num = 1] )
Send string to a attached process.
Description
The insert_process() primitive inserts the specified string or integer character value val into the process attached to the current buffer. The value shall be inserted num times, which if omitted defaults to 1.
Parameters
| val | String or integer character value to be inserted. |
| num | Option integer number stating the repeat count, if specified then the string is inserted the given number of times. If omitted, it defaults to 1. |
Returns
The insert_process() primitive returns the number of characters inserted.
Portability
n/a
See Also
perror
string perror( [int errnum = errno], string format, ... )
Print error.
Description
The perror() primitive shall map the error number specified by errnum to a language-dependent error message, which shall be written to the standard error stream as follows:
<message> : <error - description>
Parameters
| errnum | Integer value of the error condition to be decoded, if omitted the current system errno is decoded. |
Returns
The perror function returns a string containing the formatted message with a trailing description of the the error value.
Portability
A GriefEdit extenions.
See Also
send_signal
int send_signal( int signal )
Send signal to a process buffer.
Description
The send_signal() primitive send a signal to a process or a group of processes attached to the current buffer. The signal to be sent is specified by signo and is either one from the list given in Signals or 0.
If signo is 0 or omitted, then the null signal is sent, error checking is performed but no signal is actually sent.
See the unix kill system function is more details.
Parameters
| signo | Optional integer signal number, if omitted defaults to the null signal. |
Returns
The send_signal() primitive upon successful completion returns 0 and 1 when no buffer is attached. Otherwise -1 shall be returned and errno set to indicate the error.
Portability
n/a
See Also
shell
int shell( [string cmd], [int use_shell], [string completion], [string stdin], [string stdout], [string stderr], [int mode], [string spec] )
Spawn a sub-shell process.
Description
The shell primitive performs executes a command specified in cmd by creating a system dependent shell, and returns after the command has been completed.
The shell primitive can be used to create a subshell without exiting the current GriefEdit session; placing GriefEdit into the background. Without any arguments an interactive shell is created. The user terminates the sub-shell by typing the usual ^D or exit.
shell()
Alternatively the shell primitive can be used to execute an explicit command, as in the following examples.
The following example performs a uname(1) command redirecting into a output in a temporary working file for use on completion; the TRUE informs GriefEdit not to bother repainting the screen.
shell("uname 2>&1 >/tmp/uname.tmp", TRUE);The following example performs a gmake command redirecting output plus registers the macro gmake_complete to be executed on completion.
shell("gmake 2>&1 >/tmp/gmake.tmp", TRUE, "gmake_completion");associated completion macro.
void
gmake_completion(int status)
{
message("gmake done, status = %d", status);
}
Meta Characters
As the command is passed on to a command processor care should be taken with special characters (including $, ?, *, [ and ;) since the command wild-card and environment expansion will occur.
Although there is no definite syntax for wildcard operations, common features include:
| Wildcard |
Description |
|---|---|
| ? |
Matches any single character. |
| * |
Matches none or more characters. |
| [seq] |
Matches any one of the characters within the sequence. Sequences generally support ranges; two characters separated by - denote a range. (e.g. [A-Fa-f0-9] is equivalent to [ABCDEFabcdef0123456789].) |
| [!seq] |
Matches any one of the characters not contained within the sequence. |
Redirection
In addition input/output redirection is system dependent and/or shell command interpreter specific. Despite this fact the following are normally supported across all supported GriefEdit targets.
| Redirection |
Description |
|---|---|
| > |
Writes the command output to a file or a device, such as a printer, instead of the Command Prompt window. |
| < |
Reads the command input from a file, instead of reading input from the keyboard. |
| >> |
Appends the command output to the end of a file without deleting the information that is already in the file. |
| >& |
Writes the output from one handle to the input of another handle; the standard handle assignments are 0=stdin, 1=stdout and 2=stderr. |
| <& |
Reads the input from one handle and writes it to the output of another handle. |
Note:
If there is any doubt regarding portability of redirection operators it is advised to use the explicit stdin, stdout and stderr arguments.
Parameters
| cmd | Optional string containing the command to be passed to the host environment to be executed by a command processor in an implementation-dependent manner. If omitted a interactive sub-shell is created. |
| use_shell | Optional boolean value, if true forces the original display and terminal settings to the restored, and than initialised on completion of the sub-process. |
| completion | Optional string containing the name of macro to be executed on the termination of the sub-process. The completion routine is called with the first parameter set to the return status from the underlying process. Any other positional parameters are shifted up one. |
| stdin | Option string, specifies the name of the file/device from which standard input shall be source. If omitted the sub-shell standard input remains unchanged. |
| stdout | Option string, specifies the name of the file/device to which standard output shall be redirected. If omitted the sub-shell standard output remains unchanged. |
| stderr | Option string, specifies the name of the file/device to which standard error shall be redirected. If omitted the sub-shell standard error remains unchanged. |
| mode | Optional mode flags, specifies the creation mode to be utilised during stream creation. If omitted 0644 is applied. |
| spec | Optional string, reserved for future use. |
Returns
The shell primitive returns the exit status from the executed command (0 .. 256), otherwise -1 on error and sets errno to indicate the error.
| Constant |
Description |
|---|---|
| E2BIG |
Combined Size of environment and argument list is too large. |
| EACCES |
Search permission is denied on a component of the path prefix of filename or the name of a script interpreter. |
| EACCES |
The file or a script interpreter is not a regular file. |
| EACCES |
Execute permission is denied. |
| EIO |
An I/O error occurred. |
| ENAMETOOLONG |
Path is too long. |
| ENOENT |
The command or one of its components does not exist. |
| ENOEXEC |
An executable is not in a recognized format, is for the wrong architecture, or has some other format error that means it cannot be executed. |
| ENOMEM |
Insufficient kernel memory was available. |
Portability
A arguments differ from the original implementation.
See Also
sleep
void sleep( [int seconds = 1], [int milliseconds = 0] )
Suspend execution for an interval of time.
Description
The sleep() primitive causes the caller to be suspended from execution until either the specified interval specified by seconds and milliseconds has elapsed.
Note:
The suspension time may be longer than requested due to the scheduling of other activity by the system.
Parameters
| seconds | Optional positive integer stating the time-out interval seconds component, if omitted defaults to 1 second. |
| milliseconds | Option positive integer stating the time-out interval milliseconds component. |
Returns
nothing
Portability
n/a
See Also
strerror
string strerror( [int errnum = errno], [string &manifest], [int multi = FALSE] )
String error.
Description
The strerror() primitive maps the error number in errnum to a locale-dependent error message and returns a string containing the mapped condition.
Parameters
| errnum | Integer value of the error condition to be decoded, if omitted the current system errno is decoded. |
| manifest | Optional string variable which is specified shall be populated with the signal manifest. |
Returns
The strerror function returns a string descripting the error value, otherwise an empty string if undefined.
Portability
The manifest and multi options are GriefEdit extensions.
See Also
strsignal
int strsignal( int signo, [string &manifest], [int multi = FALSE] )
Return string describing signal.
Description
The strsignal() primitive returns a string describing the signal number passed in the argument signo.
Parameters
| signo | Integer value of the signal number to be decoded. |
| manifest | Optional string variable which is specified shall be populated with the signal manifest. |
Returns
The strsignal() primitive returns the appropriate description string, or an unknown signal message if the signal number is invalid.
Portability
A GriefEdit extension.
See Also
suspend
void suspend()
Suspend current process.
Description
The suspend() primitive pretends user typed ctrl-z by sending a SIGTSTP to the controlled processing, effectively suspending GriefEdit by placing it in the background.
Note:
This primitive shall only function on systems which support job control, for example unix.
Parameters
none
Returns
nothing
Portability
n/a
See Also
wait
int wait( [int &status] )
Wait for attached process to terminate.
Description
The wait() primitive suspends execution until for the process attached to the current buffer terminates, returning status information for the terminated child, or until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process.
This primitive may be aborted by pressing a space.
Parameters
| status | Optional integer variable populated with the process status. |
Returns
The wait() primitive returns 0 if the process has completed, -2 if the user aborted, otherwise -1 if no process was attached.
Portability
n/a
See Also
wait_for
int wait_for( [int timeout], list|string pattern, [int flags = 0] )
Wait for process output.
Description
The wait_for() primitive waits for a specific string of characters to be output by the current buffers attached sub-process for up to the specified time timeout.
The character sequence is in the form of regular expression pattern using the search flags flags. The pattern is either a single string expression or a list of string expressions. When a list is given, then a parallel match is performed as each character is read from the buffer.
Parameters
| timeout | Optional integer timeout in seconds, if omitted or zero the primitive blocks indefinitely until the sequence is encountered or the sub-process terminates. |
| pattern | Character sequences to be matched, as either a single string containing a regular expression or a list of string expressions. |
| flags | Optional integer stating the search flags to be applied (See: re_search). |
Returns
The wait_for() primitive returns a non-negative return on a success match, otherwise -1 if there is no process currently attached to the current buffer, or the user interrupted.
On a single string expression wait_for returns 1, otherwise upon a list of string expressions returns the matching index.
Portability
n/a
See Also
Signals
Signals are a limited form of inter-process communication used in Unix, Unix-like, and other POSIX compliant operating systems. A signal is an asynchronous notification sent to a process or to a specific thread within the same process in order to notify it of an event that occurred.
The following manifest constants are the general set of signals which may be supported representing their positive signal number, which if not supported by the underlying operating system shall have an assigned value of -1.
| Constant |
Description |
|---|---|
| SIGHUP |
Hangup (POSIX). |
| SIGINT |
Interrupt (ANSI). |
| SIGQUIT |
Quit (POSIX). |
| SIGILL |
Illegal instruction (ANSI). |
| SIGTRAP |
Trace trap (POSIX). |
| SIGABRT |
Abort (ANSI). |
| SIGIOT |
IOT trap (4.2 BSD). |
| SIGBUS |
BUS error (4.2 BSD). |
| SIGFPE |
Floating-point exception (ANSI). |
| SIGKILL |
Kill, unblockable (POSIX). |
| SIGUSR1 |
User-defined signal 1 (POSIX). |
| SIGSEGV |
Segmentation violation (ANSI). |
| SIGUSR2 |
User-defined signal 2 (POSIX). |
| SIGPIPE |
Broken pipe (POSIX). |
| SIGALRM |
Alarm clock (POSIX). |
| SIGTERM |
Termination (ANSI). |
| SIGSTKFLT |
Stack fault. |
| SIGCHLD |
Child status has changed (POSIX). |
| SIGCLD |
Same as SIGCHLD (System V). |
| SIGCONT |
Continue (POSIX). |
| SIGSTOP |
Stop, unblockable (POSIX). |
| SIGTSTP |
Keyboard stop (POSIX). |
| SIGTTIN |
Background read from tty (POSIX). |
| SIGTTOU |
Background write to tty (POSIX). |
| SIGURG |
Urgent condition on socket (4.2 BSD). |
| SIGXCPU |
CPU limit exceeded (4.2 BSD). |
| SIGXFSZ |
File size limit exceeded (4.2 BSD). |
| SIGVTALRM |
Virtual alarm clock (4.2 BSD). |
| SIGPROF |
Profiling alarm clock (4.2 BSD). |
| SIGWINCH |
Window size change (4.3 BSD, Sun). |
| SIGPOLL |
Pollable event occurred (System V). |
| SIGIO |
I/O now possible (4.2 BSD). |
| SIGPWR |
Power failure restart (System V). |
| SIGSYS |
Bad system call. |
| SIGUNKNOWN |
Unknown error |
$Id: $
To send feedback on this topic email: griefedit@gmail.com
Copyright © Adam Young All Rights Reserved.