PI Unix Library Reference

Unix Library Fuctions

The Unix library functions are created to closely resemble many commonly available C and Posix library functions which are specific to the Unix platform. These functions are not available in the Windows 32bit platform (e.g. Print Control for Windows). In many cases these directly relate to an equivalent C library function, and this will be noted under "See Also" by a reference to a standard Unix manual section 2 or section 3 entry.

alarm	Set an interval timer
dclose	Close a character special device file.
dopen	Open a character special device file.
exit	Force termination and exit from the program.
fork	Create a new process.
getpid	Get ID of the calling process.
glos_exec	Execute a shell script held in a glossary file.
kill	Send a signal to a process or process group.
link	Make a new name for a file
nice	Change priority of the calling process.
pclose	Close an interprocess pipe stream.
popen	Open an interprocess pipe stream.
sleep	Suspend execution for an interval.
termio	Set terminal interface settings.

alarm

Function Set an interval timer

IS_INTEGER alarm ( IS_INTEGER seconds );

Remarks Sets an interval time to expire after and interval of seconds duration. This is often used to force return from a read() function call, or other kernel functions which allow interruption by the SIGALRM signal. If seconds is zero, any existing interval timers will be reset.
Returns alarm returns the number of seconds remaining from a pre-existing call to the same function, or zero if there was no prior unexpired alarm interval. No condition is reserved as an error, and the function is always successful.
See also

dclose

Function Close a character special device file.

IS_INTEGER dclose ( IS_FILE fp );

Remarks Close the device file fp which was previously opened by dopen. This function will unblock the file stream (by turning on O_NDELAY) before closing it, so the function call should return immediately, regardless of the device control state.
Returns dclose returns zero upon success, or EOF upon failure.
See also dopen(), termio(), fcntl(2).

dopen

Function Open a character special device file.

IS_FILE dopen ( IS_STRING device, IS_STRING mode );

Remarks Opens the named device file, and associates a file stream with it. The argument mode is a character string with one of the following values:

"r" open for reading

"w" truncate or create for writing

"a" append; open for writing at end of file, or create for writing

"r+" open for update (reading and writing)

"w+" truncate or create for update

"a+" append; open or create for update at end-of-file

This function will unblock the file stream (by turning on O_NDELAY) when opening it, so the function call should return immediately, regardless of the device control state. But blocking will be turned on before returning, so the first attempt to read from or write to the device may block if the control state is incorrect.
Returns dopen returns an opened file stream on success, or NULL if the named device cannot be opened.
See also dclose(), fcntl(2).

exit

Function Force termination and exit from the program.

exit ( IS_INTEGER status );

Remarks The program is exited, and status will be used as the exit status of the program. This function calls the kernel function exit, and so if has all the same implications.
Returns exit will not return any result. There can be no return from an exit system call.
See also exit(2).

fork

Function Create a new process.

IS_INTEGER fork ();

Remarks Create a new process. The new process is an exact copy of the calling process. This makes a direct call to the kernel function fork, and so it has all the same implications.
Returns fork returns zero to the child process, and it returns the process ID of the new child process to the parent process. Otherwise decimal -1 is returned to the parent process, and the global variable errno is set to indicate the error.
See also fork(2).

getpid

Function Get ID of the calling process.

IS_INTEGER getpid ();

Remarks Returns the process ID (PID) of the calling process.
Returns getpid is always successful and will return the process ID as a positive integer.
See also getpid(3).

glos_exec

Function Execute a shell script held in a glossary file.

IS_INTEGER glos_exec ( IS_STRING section );

Remarks All currently opened glossary files will be searched for an matching named section. The contents of the section will be executed as a shell script.
Returns glos_exec returns exit status of the shell script.
See also glos_find(), system(3).

kill

Function Send a signal to a process or process group.

IS_INTEGER kill ( IS_INTEGER pid, IS_INTEGER signo );

Remarks Send a signal to a process or a group of processes. The process or group of processes to which the signal is to be sent is specified by pid. The signal that is to be sent is specified by signo and may be zero. If signo is 0 (the null signal), error checking is performed but no signal is actually sent. This can be used to check the validity of pid.
The real or effective user ID of the sending process must match the real or effective user ID of the receiving process, unless the effective user ID of the sending process is super user.
If pid is greater than zero, signo is sent to the process whose process ID is equal to pid.
This function is equivalant to the same kernel function, and reference should be made to that for a full description of all the available argument options.
Returns Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, and errno is set to indicate the error.
See also kill(2).

link

Function Make a new name for a file

IS_FILE popen ( IS_STRING oldpath, IS_STRING newpath );

Remarks link creates a new link (also known as a hard link) to an existing file.
If newpath exists it will not be overwritten.
This new name may be used exactly as the old one for any operation; both names refer to the same file (and so have the same permissions and ownership) and it is impossible to tell which name was the `original'.
Returns On success, zero is returned. On error, -1 is returned, and errno is set appropriately.
See also unlink(), link(3).

nice

Function Change priority of the calling process.

IS_INTEGER nice ( IS_INTEGER incr );

Remarks The nice system call adds the value of incr to the nice value of the calling process. A process's nice value is a non-negative number for which a more positive value results in lower CPU priority.
A maximum nice value of 39 and a minimum nice value of 0 are imposed by the system. (The default nice value is 20.) Requests for values above or below these limits result in the nice value being set to the corresponding limit.
Returns Upon successful completion, nice returns the new nice value minus 20. Otherwise, a value of -1 is returned, and errno is set to indicate the error.
See also nice(2).

pclose

Function Close an interprocess pipe stream.

IS_INTEGER pclose ( IS_FILE fp );

Remarks Close the interprocess pipe stream fp which was previously opened by popen.
Returns pclose returns the exit status of the command, or -1 if the stream is not associated with a pipe opened by popen.
See also popen(), pclose(3).

popen

Function Open an interprocess pipe stream.

IS_FILE popen ( IS_STRING cmd, IS_STRING type );

Remarks Creates a pipe between the calling program and the command to be executed. Cmd consists of a shell command line. type is an I/O mode, either r for reading or w for writing. The value returned is a stream pointer such that one can write to the standard input of the command, if the I/O mode is "w", by writing to the file stream; and one can read from the standard output of the command, if the I/O mode is "r", by reading from the file stream.
A stream opened by popen should be closed by pclose, which waits for the associated process to terminate and returns the exit status of the command.
Returns popen returns an opened file stream on success, or NULL if the new process cannot be created.
See also pclose(), popen(3).

sleep

Function Suspend execution for an interval.

IS_INTEGER sleep ( IS_INTEGER seconds );

Remarks The current process is suspended from execution for the number of seconds specified by the argument. This is achieved by setting an alarm interval timer. Any pre-existing alarm setting will be preserved.
Returns sleep returns the number of seconds remaining from a pre-existing call to the same function, or zero if there was no prior unexpired alarm interval. No condition is reserved as an error, and the function is always successful.
See also sleep(3).

termio

Function Set terminal interface settings.

IS_INTEGER termio ( IS_FILE fp, IS_STRING settings );

Remarks Set the state of a terminal interface which was opened with dopen. The "termio" settings are all given in a single string argument, by space separating the individual setting within the sting settings. The recognised flags (case insensitive) are;
Input Flags
IGNBRK BRKINT IGNPAR PARMRK INPCK ISTRIP INLCR
IGNCR ICRNL IXON IXOFF IUCLC IXANY
Output Flags
OPOST ONLCR OCRNL ONOCR ONLRET OLCUC OFILL OFDEL
NL0 NL1 CR0 CR1 CR2 CR3 TAB0 TAB1 TAB2 TAB3 BS0
BS1 VT0 VT1 FF0 FF1
Control Flags
110 300 1200 1800 2400 4800 9600 19200 38400 CS5
CS6 CS7 CS8 CSTOPB CREAD PARENB PARODD HUPCL
CLOCAL CTSFLOW RTSFLOW
Local Flags
ISIG ICANON XCASE ECHO ECHOE ECHOK ECHONL NOFLSH
Control Codes
VINTR VQUIT VERASE VKILL VEOF VEOL VTIME VMIN
The setting "raw" may be given separately or in combination with other settings, in which case all settings will be cleared before any others are applied. For example, the following function call puts a terminal interface into a raw character mode;
termio(fp, "raw cread hupcl vtime=0 vmin=1");
The flag settings are set by naming them within the settings argument, and resetting them by preceding their name with a dash ('-') character in the same string. The control codes are set by appending an assignment of a new value for the setting.
Returns termio returns zero on success or -1 in case of an error.
See also termio(5).