ack/man/libmon.7

.\" $Header$
.TH LIBMON 7 "$Revision$"
.ad
.SH NAME
libmon \- library of system call routines with EM calling sequence
.SH DESCRIPTION
The modules in this library contain the UNIX system calls with EM calling sequence.
This library is written in EM assembly language and can be used
for interpreted programs, and \fIa.out\fP programs.
If these routines are used in Pascal programs, then the calling sequence
requires some attention.
Some hints may be useful:
.IP -
The c-option {$c+} allows declaration of zero-terminated string
constants in Pascal like "/etc/passwd".
Moreover, the identifier \fIstring\fP is then defined as type identifier for
a pointer to these zero-terminated strings.
.IP -
The d-option {$d+} allows the use of double precision integers (longs).
The lseek system call, for instance, needs a long argument and returns a long result.
.IP -
If the system call requires a pointer as argument use a \fIvar\fP parameter.
For instance declare times as:
.br
     procedure times(var t:timesbuf); extern;
.br
Note that a \fIstring\fP is already a pointer.
.IP -
When defining types, use packed records if two bytes must be allocated
in a single word, as in
.br
     device = packed record
.br
                minor,major:0..255;
.br
              end;
.IP -
If a collection of bits is needed, then define an enumerated type and
a set of this enumerated type. The create mode of a file, for example,
can be declared as:
.br
     modebits = (XHIM,WHIM,RHIM,
.br
                 XYOU,WYOU,RYOU,
.br
                 XME, WME, RME,
.br
                 TEXT,SGID,SUID,... );
.br
     creatmode = set of XHIM..SUID;
.IP -
There are special system call routines \fIuread\fP and \fIuwrite\fP
in libpc(7),
because the names \fIread\fP and \fIwrite\fP
are blocked by similar functions in Pascal.
.PP
The system call \fIsignal\fP exists, but uses \fIsigtrp\fP.
This EM system call has the
following calling sequence:
.br
     function sigtrp(signo,trapno:integer):integer;
.br
The action values of \fIsignal\fP, odd for \fIignore\fP and zero
for \fIget back to default\fP,
may interfere with the EM procedure identification in some
implementations.
In most interpreters procedures in EM are numbered consecutively from zero up.
The first argument of \fIsigtrp\fP is the signal number \fIsigno\fP
as for \fIsignal\fP.
The second argument is an integer \fItrapno\fP,
indicating the action to be performed
when the signal is issued:
.IP -2 8
Reset the action for signal \fIsigno\fP to the default.
.IP -3
Ignore signal \fIsigno\fP.
.IP "0-252"
Perform an EM instruction TRP with error code \fItrapno\fP,
whenever the signal \fIsigno\fP is issued.
Note that the error codes 0-127 are reserved for EM machine errors
and language runtime system errors.
.PP
The routine \fIsigtrp\fP returns the old \fItrapno\fP or -1 if an erroneous
signal number is specified.
Only the signal numbers 1, 2, 3, 13, 14, 15 and 16 may be used as argument
for \fIsigtrp\fP.
.SH FILES
.IP ~em/lib/*/tail_mon
.PD
.SH "SEE ALSO"
em(1), ack(1), *(2), libpc(7)
.SH DIAGNOSTICS
All routines put the UNIX error code in the global variable \fIerrno\fP.
Errno is not cleared by successful system calls, so it always gives
the error of the last failed call.
One exception: ptrace clears errno when successful.
.SH AUTHOR
Ed Keizer, Vrije Universiteit
.SH BUGS
There should be additional routines giving a fatal error when they fail.
It would be pleasant to have routines,
which print a nice message and stop execution for unexpected errors.