[Next][Prev] [Right] [Left] [Up] [Index] [Root]

Pipes

Pipes are used to communicate with newly-created processes. Currently pipes are only available on UNIX systems.

The Magma I/O module is currently undergoing revision, and the current pipe facilities are a mix of the old and new methods. A more uniform model will be available in future releases.

Subsections

Pipe Creation

POpen(C, T) : MonStgElt, MonStgElt -> File
Given a shell command line C, together with a type indicator T, open a pipe between the Magma process and the command to be executed. The standard C library function popen() is used, so the possible characters allowed in T are the same as those allowed for that function in the current operating system, and have the same interpretation. Thus one should give the value "r" for T so that Magma can read the output from the command, and give the value "w" for T so that Magma can write into the input of the command. See the Pipe intrinsic for a method for sending input to, and receiving output from, a single command.

Important: this function returns a File object, and the I/O functions for files described previously must be used rather then those described in the following.

Pipe(C, S) : MonStgElt, MonStgElt -> MonStgElt
Given a shell command C and an input string S, create a pipe to the command C, send S into the standard input of C, and return the output of C as a string. Note that for many commands, S should finish with a new line character if it consists of only one line.

Example IO_GetTime (H3E11)

We write a function which returns the current time as 3 values: hour, minutes, seconds. The function opens a pipe to the UNIX command "date" and applies regular expression matching to the output to extract the relevant fields.

> function GetTime()
>     D := POpen("date", "r");
>     date := Gets(D);
>     _, _, f := Regexp("([0-9][0-9]):([0-9][0-9]):([0-9][0-9])", date);
>     h, m, s := Explode(f);
>     return h, m, s;
> end function;
> h, m, s := GetTime();
> h, m, s;
14 30 01
> h, m, s := GetTime();
> h, m, s;
14 30 04

Operations on Pipes

When a read request is made on a pipe, the available data is returned. If no data is currently available, then the process waits until some does becomes available, and returns that. (It will also return if the pipe has been closed and hence no more data can be transmitted.) It does not continue trying to read more data, as it cannot tell whether or not there is some "on the way".

The upshot of all this is that care must be exercised as reads may return less data than is expected.

Read(P : parameters) : IO -> MonStgElt
    Max: RngIntElt                      Default: 0
Waits for data to become available for reading from P and then returns it as a string. If the parameter Max is set to a positive value then at most that many characters will be read. Note that less than Max characters may be returned, depending on the amount of currently available data.

If the pipe has been closed then the special EOF marker string is returned.

ReadBytes(P : parameters) : IO -> SeqEnum
    Max: RngIntElt                      Default: 0
Waits for data to become available for reading from P and then returns it as a sequence of bytes (integers in the range 0 .. 255). If the parameter Max is set to a positive value then at most that many bytes will be read. Note that less than Max bytes may be returned, depending on the amount of currently available data.

If the pipe has been closed then the empty sequence is returned.

Write(P, s) : IO, MonStgElt ->
Writes the characters of the string s to the pipe P.
WriteBytes(P, Q) : IO, SeqEnum ->
Writes the bytes in the byte sequence Q to the pipe P. Each byte must be an integer in the range 0..255.
 [Next][Prev] [Right] [Left] [Up] [Index] [Root]

Version: V2.19 of Wed Apr 24 15:09:57 EST 2013