.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ici::doc::pod3::platform 3"
.TH ici::doc::pod3::platform 3 "2016-07-07" "perl v5.24.1" "ICI library functions"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
platform \- C software portability definitions and functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    #include "platform.h"
\&
\&    [see description for available functions]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIplatform\fR is a library of functions that simplify the porting of
software written in C.  It provides an \s-1API\s0 that enables application 
code to access the resources of an abstract POSIX-compliant
\&\*(L"least common denominator\*(R" operating system \*(-- typically a large
subset of the resources of the actual underlying operating system.
.PP
Most of the functionality provided by the platform library is
aimed at making communication code portable: common functions for
shared memory, semaphores, and \s-1IP\s0 sockets are provided.  
The implementation of the abstract O/S \s-1API\s0 varies according
to the actual operating system on which the application runs, but
the \s-1API\s0's behavior is always the same; applications that invoke
the platform library functions rather than native O/S system
calls may forego some O/S\-specific capability, but they gain portability 
at little if any cost in performance.
.PP
Differences in word size among platforms are implemented by values
of the \fI\s-1SPACE_ORDER\s0\fR macro.  \*(L"Space order\*(R" is the base 2 log of the
number of octets in a word: for 32\-bit machines the space order is
2 (2^2 = 4 octets per word), for 64\-bit machines it is 3 (2^3 = 8
octets per word).
.PP
A consistent platform-independent representation of large integers is
useful for some applications.  For this purpose, \fIplatform\fR defines
new types \fBvast\fR and \fBuvast\fR (unsigned vast) which are consistently
defined to be 64\-bit integers regardless of the platform's native word
size.
.PP
The platform.h header file #includes many of the most frequently
needed header files: sys/types.h, errno.h, string.h, stdio.h,
sys/socket.h, signal.h, dirent.h, netinet/in.h, unistd.h,
stdlib.h, sys/time.h, sys/resource.h, malloc.h, sys/param.h,
netdb.h, sys/uni.h, and fcntl.h.  Beyond this, \fIplatform\fR attempts 
to enhance compatibility by providing standard macros,
type definitions, external references, or function implementations 
that are missing from a few supported O/S's but supported
by all others.  Finally, entirely new, generic functions are provided 
to establish a common body of functionality that subsumes
significantly different O/S\-specific capabilities.
.SS "\s-1PLATFORM COMPATIBILITY PATCHES\s0"
.IX Subsection "PLATFORM COMPATIBILITY PATCHES"
The platform library \*(L"patches\*(R" the APIs of supported O/S's to
guarantee that all of the following items may be utilized by application 
software:
.PP
.Vb 1
\&    The strchr(), strrchr(), strcasecmp(), and strncasecmp() functions.
\&
\&    The unlink(), getpid(), and gettimeofday() functions.
\&
\&    The select() function.
\&
\&    The FD_BITMAP macro (used by select()).
\&
\&    The MAXHOSTNAMELEN macro.
\&
\&    The NULL macro.
\&
\&    The timer_t type definition.
.Ve
.SS "\s-1PLATFORM GENERIC MACROS AND FUNCTIONS\s0"
.IX Subsection "PLATFORM GENERIC MACROS AND FUNCTIONS"
The generic macros and functions in this section may be used in
place of comparable O/S\-specific functions, to enhance the portability 
of code.  (The implementations of these macros and functions are 
no-ops in environments in which they are inapplicable,
so they're always safe to call.)
.IP "\s-1FDTABLE_SIZE\s0" 4
.IX Item "FDTABLE_SIZE"
The \s-1FDTABLE_SIZE\s0 macro returns the total number of file
descriptors defined for the process (or VxWorks target).
.IP "\s-1ION_PATH_DELIMITER\s0" 4
.IX Item "ION_PATH_DELIMITER"
The \s-1ION_PATH_DELIMITER\s0 macro returns the \s-1ASCII\s0 character \*(-- either '/' or
\&'\e' \*(-- that is used as a directory name delimiter in path names for the
file system used by the local platform.
.IP "oK(expression)" 4
.IX Item "oK(expression)"
The oK macro simply casts the value of \fIexpression\fR to void, a way of
handling function return codes that are not meaningful in this context.
.IP "\s-1CHKERR\s0(condition)" 4
.IX Item "CHKERR(condition)"
The \s-1CHKERR\s0 macro is an \*(L"assert\*(R" mechanism.  It causes the calling function
to return \-1 immediately if \fIcondition\fR is false.
.IP "\s-1CHKZERO\s0(condition)" 4
.IX Item "CHKZERO(condition)"
The \s-1CHKZERO\s0 macro is an \*(L"assert\*(R" mechanism.  It causes the calling function
to return 0 immediately if \fIcondition\fR is false.
.IP "\s-1CHKNULL\s0(condition)" 4
.IX Item "CHKNULL(condition)"
The \s-1CHKNULL\s0 macro is an \*(L"assert\*(R" mechanism.  It causes the calling function
to return \s-1NULL\s0 immediately if \fIcondition\fR is false.
.IP "\s-1CHKVOID\s0(condition)" 4
.IX Item "CHKVOID(condition)"
The \s-1CHKVOID\s0 macro is an \*(L"assert\*(R" mechanism.  It causes the calling function
to return immediately if \fIcondition\fR is false.
.IP "void snooze(unsigned int seconds)" 4
.IX Item "void snooze(unsigned int seconds)"
Suspends execution of the invoking task or process for the indicated 
number of seconds.
.IP "void microsnooze(unsigned int microseconds)" 4
.IX Item "void microsnooze(unsigned int microseconds)"
Suspends execution of the invoking task or process for
the indicated number of microseconds.
.IP "void getCurrentTime(struct timeval *time)" 4
.IX Item "void getCurrentTime(struct timeval *time)"
Returns the current local time in a timeval structure (see gettimeofday(3C)).
.IP "void isprintf(char *buffer, int bufSize, char *format, ...)" 4
.IX Item "void isprintf(char *buffer, int bufSize, char *format, ...)"
\&\fIisprintf()\fR is a safe, portable implementation of \fIsnprintf()\fR; see the
snprintf(P) man page for details.  \fIisprintf()\fR differs from \fIsnprintf()\fR in that
it always NULL-terminates the string in \fIbuffer\fR, even if the length of the
composed string would equal or exceed \fIbufSize\fR.  Buffer overruns are
reported by log message; unlike \fIsnprintf()\fR, \fIisprintf()\fR returns void.
.IP "size_t istrlen(const char *sourceString, size_t maxlen)" 4
.IX Item "size_t istrlen(const char *sourceString, size_t maxlen)"
\&\fIistrlen()\fR is a safe implementation of \fIstrlen()\fR; see the \fIstrlen\fR\|(3) man 
page for details.  \fIistrlen()\fR differs from \fIstrlen()\fR in that it takes a second
argument, the maximum valid length of \fIsourceString\fR.  The function
returns the number of non-NULL characters in \fIsourceString\fR preceding
the first \s-1NULL\s0 character in \fIsourceString\fR, provided that a \s-1NULL\s0
character appears somewhere within the first \fImaxlen\fR characters of
\&\fIsourceString\fR; otherwise it returns \fImaxlen\fR.
.IP "char *istrcpy(char *buffer, char *sourceString, int bufSize)" 4
.IX Item "char *istrcpy(char *buffer, char *sourceString, int bufSize)"
\&\fIistrcpy()\fR is a safe implementation of \fIstrcpy()\fR; see the \fIstrcpy\fR\|(3) man
page for details.  \fIistrcpy()\fR differs from \fIstrcpy()\fR in that it takes a
third argument, the total size of the buffer into which \fIsourceString\fR
is to be copied.  \fIistrcpy()\fR always NULL-terminates the string in \fIbuffer\fR,
even if the length of \fIsourceString\fR string would equal or exceed
\&\fIbufSize\fR (in which case \fIsourceString\fR is truncated to fit within
the buffer).
.IP "char *istrcat(char *buffer, char *sourceString, int bufSize)" 4
.IX Item "char *istrcat(char *buffer, char *sourceString, int bufSize)"
\&\fIistrcat()\fR is a safe implementation of \fIstrcat()\fR; see the \fIstrcat\fR\|(3) man
page for details.  \fIistrcat()\fR differs from \fIstrcat()\fR in that it takes a
third argument, the total size of the buffer for the string that is being
aggregated. \fIistrcat()\fR always NULL-terminates the string in \fIbuffer\fR, even
if the length of \fIsourceString\fR string would equal or exceed the sum of
\&\fIbufSize\fR and the length of the string currently occupying the buffer
(in which case \fIsourceString\fR is truncated to fit within the buffer).
.IP "char *igetcwd(char *buf, size_t size)" 4
.IX Item "char *igetcwd(char *buf, size_t size)"
\&\fIigetcwd()\fR is normally just a wrapper around \fIgetcwd\fR\|(3).  It differs from
\&\fIgetcwd\fR\|(3) only when \s-1FSWWDNAME\s0 is defined, in which case the implementation
of \fIigetcwd()\fR must be supplied in an included file named \*(L"wdname.c\*(R"; this
adaptation option accommodates flight software environments in which the
current working directory name must be configured rather than discovered
at run time.
.IP "void isignal(int signbr, void (*handler)(int))" 4
.IX Item "void isignal(int signbr, void (*handler)(int))"
\&\fIisignal()\fR is a portable, simplified interface to signal handling that is
functionally indistinguishable from signal(P).  It assures that reception
of the indicated signal will interrupt system calls in \s-1SVR4\s0 fashion, even
when running on a FreeBSD platform.
.IP "void iblock(int signbr)" 4
.IX Item "void iblock(int signbr)"
\&\fIiblock()\fR simply prevents reception of the indicated signal by the calling
thread.  It provides a means of controlling which of the threads in a process
will receive the signal cited in an invocation of \fIisignal()\fR.
.IP "char *igets(int fd, char *buffer, int buflen, int *lineLen)" 4
.IX Item "char *igets(int fd, char *buffer, int buflen, int *lineLen)"
\&\fIigets()\fR reads a line of text, delimited by a newline character, from \fIfd\fR
into \fIbuffer\fR and writes a \s-1NULL\s0 character at the end of the string.  The
newline character itself is omitted from the NULL-terminated text line in
\&\fIbuffer\fR; if the newline is immediately preceded by a carriage return
character (i.e., the line is from a \s-1DOS\s0 text file), then the carriage return
character is likewise omitted from the NULL-terminated text line in
\&\fIbuffer\fR.  End of file is interpreted as an implicit newline, terminating
the line.  If the number of characters preceding the newline is greater
than or equal to \fIbuflen\fR, only the first (\fIbuflen\fR \- 1) characters of
the line are written into \fIbuffer\fR.  On error the function sets \fI*lineLen\fR
to \-1 and returns \s-1NULL. \s0 On reading end-of-file, the function sets \fI*lineLen\fR
to zero and returns \s-1NULL. \s0 Otherwise the function sets \fI*lineLen\fR to the
length of the text line in \fIbuffer\fR, as if from \fIstrlen\fR\|(3), and returns
\&\fIbuffer\fR.
.IP "int iputs(int fd, char *string)" 4
.IX Item "int iputs(int fd, char *string)"
\&\fIiputs()\fR writes to \fIfd\fR the NULL-terminated character string at \fIstring\fR.  No
terminating newline character is appended to \fIstring\fR by \fIiputs()\fR.  On error
the function returns \-1; otherwise the function returns the length of the
character string written to \fIfd\fR, as if from \fIstrlen\fR\|(3).
.IP "vast strtovast(char *string)" 4
.IX Item "vast strtovast(char *string)"
Converts the leading characters of \fIstring\fR, skipping leading white space
and ending at the first subsequent character that can't be interpreted as
contributing to a numeric value, to a \fBvast\fR integer and returns that integer.
.IP "uvast strtouvast(char *string)" 4
.IX Item "uvast strtouvast(char *string)"
Same as \fIstrtovast()\fR except the result is an unsigned \fBvast\fR integer value.
.IP "void findToken(char **cursorPtr, char **token)" 4
.IX Item "void findToken(char **cursorPtr, char **token)"
Locates the next non-whitespace lexical token in a character array, starting
at \fI*cursorPtr\fR.  The function NULL-terminates that token within the array
and places a pointer to the token in \fI*token\fR.  Also accommodates tokens
enclosed within matching single quotes, which may contain embedded spaces
and escaped single-quote characters.  If no token is found, \fI*token\fR contains
\&\s-1NULL\s0 on return from this function.
.IP "void *acquireSystemMemory(size_t size)" 4
.IX Item "void *acquireSystemMemory(size_t size)"
Uses \fImemalign()\fR to allocate a block of system memory of length \fIsize\fR,
starting at an address that is guaranteed to be an integral multiple of
the size of a pointer to void, and initializes the entire block to binary
zeroes.  Returns the starting address of the allocated block on success;
returns \s-1NULL\s0 on any error.
.IP "int createFile(const char *name, int flags)" 4
.IX Item "int createFile(const char *name, int flags)"
Creates a file of the indicated name, using the indicated file creation flags.
This function provides common file creation functionality across VxWorks and
Unix platforms, invoking \fIcreat()\fR under VxWorks and \fIopen()\fR elsewhere.  For
return values, see \fIcreat\fR\|(2) and \fIopen\fR\|(2).
.IP "unsigned int getInternetAddress(char *hostName)" 4
.IX Item "unsigned int getInternetAddress(char *hostName)"
Returns the \s-1IP\s0 address of the indicated host machine, or zero if the
address cannot be determined.
.IP "char *getInternetHostName(unsigned int hostNbr, char *buffer)" 4
.IX Item "char *getInternetHostName(unsigned int hostNbr, char *buffer)"
Writes the host name of the indicated host machine into \fIbuffer\fR and
returns \fIbuffer\fR, or returns \s-1NULL\s0 on any error.  The size of \fIbuffer\fR
should be (\s-1MAXHOSTNAMELEN + 1\s0).
.IP "int getNameOfHost(char *buffer, int bufferLength)" 4
.IX Item "int getNameOfHost(char *buffer, int bufferLength)"
Writes the first (\fIbufferLength\fR \- 1) characters of the
host name of the local machine into \fIbuffer\fR.  Returns 0 on success, \-1 on
any error.
.IP "unsigned int \fIgetAddressOfHost()\fR" 4
.IX Item "unsigned int getAddressOfHost()"
Returns the \s-1IP\s0 address for the host name of the local machine, or 0 on any
error.
.IP "void parseSocketSpec(char *socketSpec, unsigned short *portNbr, unsigned int *hostNbr)" 4
.IX Item "void parseSocketSpec(char *socketSpec, unsigned short *portNbr, unsigned int *hostNbr)"
Parses \fIsocketSpec\fR, extracting host number (\s-1IP\s0 address) and port number from
the string.  \fIsocketSpec\fR is expected to be of the form
\&\*(L"{ @ | hostname }[:<portnbr>]\*(R", where @ signifies \*(L"the host name of the
local machine\*(R".  If host number can be determined, writes it into \fI*hostNbr\fR;
otherwise writes 0 into \fI*hostNbr\fR.  If port number is supplied and
is in the range 1024 to 65535, writes it into \fI*portNbr\fR; otherwise writes
0 into \fI*portNbr\fR.
.IP "void printDottedString(unsigned int hostNbr, char *buffer)" 4
.IX Item "void printDottedString(unsigned int hostNbr, char *buffer)"
Composes a dotted-string (xxx.xxx.xxx.xxx) representation of the IPv4 address
in \fIhostNbr\fR and writes that string into \fIbuffer\fR.  The length of \fIbuffer\fR
must be at least 16.
.IP "char *getNameOfUser(char *buffer)" 4
.IX Item "char *getNameOfUser(char *buffer)"
Writes the user name of the invoking task or process
into \fIbuffer\fR and returns \fIbuffer\fR.  The size of \fIbuffer\fR
must be at least \fIL_cuserid\fR, a constant defined in the
stdio.h header file.  Returns \fIbuffer\fR.
.IP "int reUseAddress(int fd)" 4
.IX Item "int reUseAddress(int fd)"
Makes the address that is bound to the socket identified by 
\&\fIfd\fR reusable, so that the socket can be closed
and immediately reopened and re-bound to the same port number.
Returns 0 on success, \-1 on any error.
.IP "int makeIoNonBlocking(int fd)" 4
.IX Item "int makeIoNonBlocking(int fd)"
Makes I/O on the socket identified by \fIfd\fR non-blocking; returns \-1 on
failure.  An attempt to read on a non-blocking socket when no data are pending, 
or to write on it when its output buffer is full, will not block; 
it will instead return \-1 and cause errno to be set to \s-1EWOULDBLOCK.\s0
.IP "int watchSocket(int fd)" 4
.IX Item "int watchSocket(int fd)"
Turns on the \*(L"linger\*(R" and \*(L"keepalive\*(R" options for the
socket identified by \fIfd\fR.  See \fIsocket\fR\|(2) for details.  Returns 0 on
success, \-1 on any failure.
.IP "void closeOnExec(int fd)" 4
.IX Item "void closeOnExec(int fd)"
Ensures that \fIfd\fR will \s-1NOT\s0 be open in any child process
\&\fIfork()\fRed from the invoking process.  Has no effect on a VxWorks platform.
.SS "\s-1EXCEPTION REPORTING\s0"
.IX Subsection "EXCEPTION REPORTING"
The functions in this section offer platform-independent capabilities
for reporting on processing exceptions.
.PP
The underlying mechanism for \s-1ICI\s0's exception reporting is a pair of
functions that record error messages in a privately managed pool of
static memory.  These functions \*(-- \fIpostErrmsg()\fR and \fIpostSysErrmsg()\fR \*(--
are designed to return very rapidly with no possibility of failing,
themselves.  Nonetheless they are not safe to call from an interrupt
service routing (\s-1ISR\s0).  Although each merely copies its text to the
next available location in the error message memory pool, that pool
is protected by a mutex; multiple processes might be queued up to
take that mutex, so the total time to execute the function is
non-deterministic.
.PP
Built on top of \fIpostErrmsg()\fR and \fIpostSysErrmsg()\fR are the \fIputErrmsg()\fR
and \fIputSysErrmsg()\fR functions, which may take longer to return.  Each
one simply calls the corresponding \*(L"post\*(R" function but then calls the
\&\fIwriteErrmsgMemos()\fR function, which calls \fIwriteMemo()\fR to print (or
otherwise deliver) each message currently posted to the pool and
then destroys all of those posted messages, emptying the pool.
.PP
Recommended general policy on using the \s-1ICI\s0 exception reporting functions
(which the functions in the \s-1ION\s0 distribution libraries are supposed to
adhere to) is as follows:
.PP
.Vb 4
\&        In the implementation of any ION library function or any ION
\&        task\*(Aqs top\-level driver function, any condition that prevents
\&        the function from continuing execution toward producing the
\&        effect it is designed to produce is considered an "error".
\&
\&        Detection of an error should result in the printing of an
\&        error message and, normally, the immediate return of whatever
\&        return value is used to indicate the failure of the function
\&        in which the error was detected.  By convention this value
\&        is usually \-1, but both zero and NULL are appropriate
\&        failure indications under some circumstances such as object
\&        creation.
\&
\&        The CHKERR, CHKZERO, CHKNULL, and CHKVOID macros are used to
\&        implement this behavior in a standard and lexically terse
\&        manner.  Use of these macros offers an additional feature:
\&        for debugging purposes, they can easily be configured to
\&        call sm_Abort() to terminate immediately with a core dump
\&        instead of returning a error indication.  This option is
\&        enabled by setting the compiler parameter CORE_FILE_NEEDED
\&        to 1 at compilation time.
\&
\&        In the absence of either any error, the function returns a
\&        value that indicates nominal completion.  By convention this
\&        value is usually zero, but under some circumstances other
\&        values (such as pointers or addresses) are appropriate
\&        indications of nominal completion.  Any additional information
\&        produced by the function, such as an indication of "success",
\&        is usually returned as the value of a reference argument.
\&        [Note, though, that database management functions and the
\&        SDR hash table management functions deviate from this rule:
\&        most return 0 to indicate nominal completion but functional
\&        failure (e.g., duplicate key or object not found) and return
\&        1 to indicate functional success.]
\&
\&        So when returning a value that indicates nominal completion
\&        of the function \-\- even if the result might be interpreted
\&        as a failure at a higher level (e.g., an object identified
\&        by a given string is not found, through no failure of the
\&        search function) \-\- do NOT invoke putErrmsg().
\&
\&        Use putErrmsg() and putSysErrmsg() only when functions are
\&        unable to proceed to nominal completion.  Use writeMemo()
\&        or writeMemoNote() if you just want to log a message.
\&
\&        Whenever returning a value that indicates an error:
\&
\&                If the failure is due to the failure of a system call
\&                or some other non\-ION function, assume that errno
\&                has already been set by the function at the lowest
\&                layer of the call stack; use putSysErrmsg (or
\&                postSysErrmsg if in a hurry) to describe the nature
\&                of the activity that failed.  The text of the error
\&                message should normally start with a capital letter
\&                and should NOT end with a period.
\&
\&                Otherwise \-\- i.e., the failure is due to a condition
\&                that was detected within ION \-\- use putErrmsg (or
\&                postErrmg if pressed for time) to describe the nature
\&                of the failure condition.  This will aid in tracing
\&                the failure through the function stack in which the
\&                failure was detected.  The text of the error message
\&                should normally start with a capital letter and should
\&                end with a period.
\&
\&        When a failure in a called function is reported to "driver"
\&        code in an application program, before continuing or exiting
\&        use writeErrmsgMemos() to empty the message pool and print a
\&        simple stack trace identifying the failure.
.Ve
.IP "char *system_error_msg( )" 4
.IX Item "char *system_error_msg( )"
Returns a brief text string describing the current system error, as identified
by the current value of errno.
.IP "void setLogger(Logger usersLoggerName)" 4
.IX Item "void setLogger(Logger usersLoggerName)"
Sets the user function to be used for writing messages to a user-defined \*(L"log\*(R"
medium.  The logger function's calling sequence must match the following
prototype:
.Sp
.Vb 1
\&        void    usersLoggerName(char *msg);
.Ve
.Sp
The default Logger function simply writes the message to standard output.
.IP "void writeMemo(char *msg)" 4
.IX Item "void writeMemo(char *msg)"
Writes one log message, using the currently defined message logging function.
.IP "void writeMemoNote(char *msg, char *note)" 4
.IX Item "void writeMemoNote(char *msg, char *note)"
Writes a log message like \fIwriteMemo()\fR, accompanied by the user-supplied
context-specific text in \fInote\fR.
.IP "void writeErrMemo(char *msg)" 4
.IX Item "void writeErrMemo(char *msg)"
Writes a log message like \fIwriteMemo()\fR, accompanied by text describing the
current system error.
.IP "char *itoa(int value)" 4
.IX Item "char *itoa(int value)"
Returns a string representation of the signed integer in \fIvalue\fR, nominally
for immediate use as an argument to \fIputErrmsg()\fR.  [Note that the string is
constructed in a static buffer; this function is not thread\-safe.]
.IP "char *utoa(unsigned int value)" 4
.IX Item "char *utoa(unsigned int value)"
Returns a string representation of the unsigned integer in \fIvalue\fR, nominally
for immediate use as an argument to \fIputErrmsg()\fR.  [Note that the string is
constructed in a static buffer; this function is not thread\-safe.]
.IP "void postErrmsg(char *text, char *argument)" 4
.IX Item "void postErrmsg(char *text, char *argument)"
Constructs an error message noting the name of the source file containing
the line at which this function was called, the line number, the \fItext\fR of
the message, and \*(-- if not \s-1NULL\s0 \*(-- a single textual \fIargument\fR that can be
used to give more specific information about the nature of the reported
failure (such as the value of one of the arguments to the failed
function).  The error message is appended to the list of messages in
a privately managed pool of static memory, \s-1ERRMSGS_BUFSIZE\s0 bytes in length.
.Sp
If \fItext\fR is \s-1NULL\s0 or is a string of zero length or begins with a newline
character (i.e., \fI*text\fR == '\e0' or '\en'), the function returns immediately
and no error message is recorded.
.Sp
The errmsgs pool is designed to be large enough to contain error messages
from all levels of the calling stack at the time that an error is
encountered.  If the remaining unused space in the pool is less than
the size of the new error message, however, the error message is silently
omitted.  In this case, provided at least two bytes of unused space remain
in the pool, a message comprising a single newline character is appended to
the list to indicate that a message was omitted due to excessive length.
.IP "void postSysErrmsg(char *text, char *arg)" 4
.IX Item "void postSysErrmsg(char *text, char *arg)"
Like \fIpostErrmsg()\fR except that the error message constructed by the function
additionally contains text describing the current system error.  \fItext\fR is
truncated as necessary to assure that the sum of its length and that of
the description of the current system error does not exceed 1021 bytes.
.IP "int getErrmsg(char *buffer)" 4
.IX Item "int getErrmsg(char *buffer)"
Copies the oldest error message in the message pool into \fIbuffer\fR and
removes that message from the pool, making room for new messages.  Returns
zero if the message pool cannot be locked for update or there are no more
messages in the pool; otherwise returns the length of the message copied
into \fIbuffer\fR.  Note that, for safety, the size of \fIbuffer\fR should be
\&\s-1ERRMSGS_BUFSIZE.\s0
.Sp
Note that a returned error message comprising only a single newline character
always signifies an error message that was silently omitted because there
wasn't enough space left on the message pool to contain it.
.IP "void writeErrmsgMemos( )" 4
.IX Item "void writeErrmsgMemos( )"
Calls \fIgetErrmsg()\fR repeatedly until the message pool is empty, using
\&\fIwriteMemo()\fR to log all the messages in the pool.  Messages that were
omitted due to excessive length are indicated by logged lines of the
form \*(L"[message omitted due to excessive length]\*(R".
.IP "void putErrmsg(char *text, char *argument)" 4
.IX Item "void putErrmsg(char *text, char *argument)"
The \fIputErrmsg()\fR function merely calls \fIpostErrmsg()\fR and then
\&\fIwriteErrmsgMemos()\fR.
.IP "void putSysErrmsg(char *text, char *arg)" 4
.IX Item "void putSysErrmsg(char *text, char *arg)"
The \fIputSysErrmsg()\fR function merely calls \fIpostSysErrmsg()\fR and then
\&\fIwriteErrmsgMemos()\fR.
.IP "void discardErrmsgs( )" 4
.IX Item "void discardErrmsgs( )"
Calls \fIgetErrmsg()\fR repeatedly until the message pool is empty, discarding all
of the messages.
.IP "void printStackTrace( )" 4
.IX Item "void printStackTrace( )"
On Linux machines only, uses \fIwriteMemo()\fR to print a trace of the process's
current execution stack, starting with the lowest level of the stack and
proceeding to the \fImain()\fR function of the executable.
.Sp
Note that (a) \fIprintStackTrace()\fR is \fBonly\fR implemented for Linux platforms
at this time; (b) symbolic names of functions can only be printed if the
\&\fI\-rdynamic\fR flag was enabled when the executable was linked; (c) only the
names of non-static functions will appear in the stack trace.
.Sp
For more complete information about the state of the executable at the time
the stack trace snapshot was taken, use the Linux \fIaddr2line\fR tool. To do
this, cd into a directory in which the executable file resides (such as
/opt/bin) and submit an addr2line command as follows:
.RS 4
.Sp
.RS 4
addr2line \-e \fIname_of_executable\fR \fIstack_frame_address\fR
.RE
.RE
.RS 4
.Sp
where both \fIname_of_executable\fR and \fIstack_frame_address\fR are taken from
one of the lines of the printed stack trace.  addr2line will print the source
file name and line number for that stack frame.
.RE
.SS "\s-1WATCH CHARACTERS\s0"
.IX Subsection "WATCH CHARACTERS"
The functions in this section offer platform-independent capabilities
for recording \*(L"watch\*(R" characters indicating the occurrence of protocol
events.  See \fIbprc\fR\|(5), \fIltprc\fR\|(5), \fIcfdprc\fR\|(5), etc. for details of the
watch character production options provided by the protocol packages.
.IP "void setWatcher(Watcher usersWatcherName)" 4
.IX Item "void setWatcher(Watcher usersWatcherName)"
Sets the user function to be used for recording watch characters to a
user-defined \*(L"watch\*(R" medium.  The watcher function's calling sequence
must match the following prototype:
.Sp
.Vb 1
\&        void    usersWatcherName(char token);
.Ve
.Sp
The default Watcher function simply writes the token to standard output.
.IP "void iwatch(char token)" 4
.IX Item "void iwatch(char token)"
Records one \*(L"watch\*(R" character, using the currently defined watch character
recording function.
.SS "SELF-DELIMITING \s-1NUMERIC VALUES \s0(\s-1SDNV\s0)"
.IX Subsection "SELF-DELIMITING NUMERIC VALUES (SDNV)"
The functions in this section encode and decode SDNVs, portable variable-length
numeric variables that expand to whatever size is necessary to contain the
values they contain.  SDNVs are used extensively in the \s-1BP\s0 and \s-1LTP\s0 libraries.
.IP "void encodeSdnv(Sdnv *sdnvBuffer, uvast value)" 4
.IX Item "void encodeSdnv(Sdnv *sdnvBuffer, uvast value)"
Determines the number of octets of \s-1SDNV\s0 text needed to contain the value,
places that number in the \fIlength\fR field of the \s-1SDNV\s0 buffer, and encodes
the value in \s-1SDNV\s0 format into the first \fIlength\fR octets of the \fItext\fR field
of the \s-1SDNV\s0 buffer.
.IP "int decodeSdnv(uvast *value, unsigned char *sdnvText)" 4
.IX Item "int decodeSdnv(uvast *value, unsigned char *sdnvText)"
Determines the length of the \s-1SDNV\s0 located at \fIsdnvText\fR and returns this
number after extracting the \s-1SDNV\s0's value from those octets and storing it
in \fIvalue\fR.  Returns 0 if the encoded number value will not fit into an
unsigned vast integer.
.SS "\s-1ARITHMETIC ON LARGE INTEGERS \s0(\s-1SCALARS\s0)"
.IX Subsection "ARITHMETIC ON LARGE INTEGERS (SCALARS)"
The functions in this section perform simple arithmetic operations on
unsigned Scalar objects \*(-- structures encapsulating large positive
integers in a machine-independent way.  Each Scalar comprises two
integers, a count of units [ranging from 0 to (2^30 \- 1), i.e., up
to 1 gig] and a count of gigs [ranging from 0 to (2^31 \-1)].  A
Scalar can represent a numeric value up to 2 billion billions,
i.e., 2 million trillions.
.IP "void loadScalar(Scalar *scalar, signed int value)" 4
.IX Item "void loadScalar(Scalar *scalar, signed int value)"
Sets the value of \fIscalar\fR to the absolute value of \fIvalue\fR.
.IP "void increaseScalar(Scalar *scalar, signed int value)" 4
.IX Item "void increaseScalar(Scalar *scalar, signed int value)"
Adds to \fIscalar\fR the absolute value of \fIvalue\fR.
.IP "void reduceScalar(Scalar *scalar, signed int value)" 4
.IX Item "void reduceScalar(Scalar *scalar, signed int value)"
Adds to \fIscalar\fR the absolute value of \fIvalue\fR.
.IP "void multiplyScalar(Scalar *scalar, signed int value)" 4
.IX Item "void multiplyScalar(Scalar *scalar, signed int value)"
Multiplies \fIscalar\fR by the absolute value of \fIvalue\fR.
.IP "void divideScalar(Scalar *scalar, signed int value)" 4
.IX Item "void divideScalar(Scalar *scalar, signed int value)"
Divides \fIscalar\fR by the absolute value of \fIvalue\fR.
.IP "void copyScalar(Scalar *to, Scalar *from)" 4
.IX Item "void copyScalar(Scalar *to, Scalar *from)"
Copies the value of \fIfrom\fR into \fIto\fR.
.IP "void addToScalar(Scalar *scalar, Scalar *increment)" 4
.IX Item "void addToScalar(Scalar *scalar, Scalar *increment)"
Adds \fIincrement\fR (a Scalar rather than a C integer) to \fIscalar\fR.
.IP "void subtractFromScalar(Scalar *scalar, Scalar *decrement)" 4
.IX Item "void subtractFromScalar(Scalar *scalar, Scalar *decrement)"
Subtracts \fIdecrement\fR (a Scalar rather than a C integer) from \fIscalar\fR.
.IP "int scalarIsValid(Scalar *scalar)" 4
.IX Item "int scalarIsValid(Scalar *scalar)"
Returns 1 if the arithmetic performed on \fIscalar\fR has not resulted in
overflow or underflow.
.IP "int scalarToSdnv(Sdnv *sdnv, Scalar *scalar)" 4
.IX Item "int scalarToSdnv(Sdnv *sdnv, Scalar *scalar)"
If \fIscalar\fR points to a valid Scalar, stores the value of \fIscalar\fR in
\&\fIsdnv\fR; otherwise sets the length of \fIsdnv\fR to zero.
.IP "int sdnvToScalar(Scalar *scalar, unsigned char *sdnvText)" 4
.IX Item "int sdnvToScalar(Scalar *scalar, unsigned char *sdnvText)"
If \fIsdnvText\fR points to a sequence of bytes that, when interpreted as
the text of an Sdnv, has a value that can be represented in a 61\-bit
unsigned binary integer, then this function stores that value in \fIscalar\fR
and returns the detected Sdnv length.  Otherwise returns zero.
.Sp
Note that Scalars and Sdnvs are both representations of potentially large
unsigned integer values.  Any Scalar can alternatively be represented as
an Sdnv.  However, it is possible for a valid Sdnv to be too large to
represent in a Scalar.
.SS "\s-1PRIVATE MUTEXES\s0"
.IX Subsection "PRIVATE MUTEXES"
The functions in this section provide platform-independent management of
mutexes for synchronizing operations of threads or tasks in a common private
address space.
.IP "int initResourceLock(ResourceLock *lock)" 4
.IX Item "int initResourceLock(ResourceLock *lock)"
Establishes an inter-thread lock for use in locking some resource.  Returns
0 if successful, \-1 if not.
.IP "void killResourceLock(ResourceLock *lock)" 4
.IX Item "void killResourceLock(ResourceLock *lock)"
Deletes the resource lock referred to by \fIlock\fR.
.IP "void lockResource(ResourceLock *lock)" 4
.IX Item "void lockResource(ResourceLock *lock)"
Checks the state of \fIlock\fR.  If the lock is already
owned by a different thread, the call blocks until the
other thread relinquishes the lock.  If the lock is
unowned, it is given to the current thread and the lock
count is set to 1.  If the lock is already owned by
this thread, the lock count is incremented by 1.
.IP "void unlockResource(ResourceLock *lock)" 4
.IX Item "void unlockResource(ResourceLock *lock)"
If called by the current owner of \fIlock\fR, decrements \fIlock\fR's
lock count by 1; if zero, relinquishes the lock so it may be
taken by other threads.  Care must be taken to make sure that one, and
only one, \fIunlockResource()\fR call is issued for each
\&\fIlockResource()\fR call issued on a given resource lock.
.SS "\s-1SHARED MEMORY IPC DEVICES\s0"
.IX Subsection "SHARED MEMORY IPC DEVICES"
The functions in this section provide platform-independent management of
\&\s-1IPC\s0 mechanisms for synchronizing operations of threads, tasks, or processes
that may occupy different address spaces but share access to a common system
(nominally, processor) memory.
.PP
\&\fI\s-1NOTE\s0\fR that this is distinct from the VxWorks \*(L"VxMP\*(R" capability enabling
tasks to share access to bus memory or dual-ported board memory from multiple
processors.  The \*(L"platform\*(R" system will support \s-1IPC\s0 devices that 
utilize this capability at some time in the future, but that support is
not yet implemented.
.IP "int sm_ipc_init( )" 4
.IX Item "int sm_ipc_init( )"
Acquires and initializes shared-memory \s-1IPC\s0 management resources.  Must be
called before any other shared-memory \s-1IPC\s0 function is called.  Returns 0
on success, \-1 on any failure.
.IP "void sm_ipc_stop( )" 4
.IX Item "void sm_ipc_stop( )"
Releases shared-memory \s-1IPC\s0 management resources, disabling the shared-memory
\&\s-1IPC\s0 functions until \fIsm_ipc_init()\fR is called again.
.IP "int sm_GetUniqueKey( )" 4
.IX Item "int sm_GetUniqueKey( )"
Some of the \*(L"sm_\*(R" (shared memory) functions described
below associate new communication objects with \fIkey\fR
values that uniquely identify them, so that different
processes can access them independently.  Key values
are typically defined as constants in application code.
However, when a new communication object is required
for which no specific need was anticipated in the application, 
the \fIsm_GetUniqueKey()\fR function can be invoked to obtain a new,
arbitrary key value that is known not to be already in use.
.IP "sm_SemId sm_SemCreate(int key, int semType)" 4
.IX Item "sm_SemId sm_SemCreate(int key, int semType)"
Creates a shared-memory semaphore that can be used to
synchronize activity among tasks or processes residing
in a common system memory but possibly multiple address
spaces; returns a reference handle for that semaphore,
or \s-1SM_SEM_NONE\s0 on any failure.  If \fIkey\fR refers to an existing
semaphore, returns the handle of that semaphore.  If
\&\fIkey\fR is the constant value \s-1SM_NO_KEY,\s0 automatically
obtains an unused key.  On VxWorks platforms, \fIsemType\fR
determines the order in which the semaphore
is given to multiple tasks that attempt to take it while
it is already taken: if set to \s-1SM_SEM_PRIORITY\s0 then the
semaphore is given to tasks in task priority sequence (i.e.,
the highest-priority task waiting for it receives it when
it is released), while otherwise (\s-1SM_SEM_FIFO\s0) the semaphore
is given to tasks in the order in which they attempted to take
it.  On all other platforms, only \s-1SM_SEM_FIFO\s0 behavior is
supported and \fIsemType\fR is ignored.
.IP "int sm_SemTake(sm_SemId semId)" 4
.IX Item "int sm_SemTake(sm_SemId semId)"
Blocks until the indicated semaphore is no longer taken by any other
task or process, then takes it.  Return 0 on success, \-1 on any error.
.IP "void sm_SemGive(sm_SemId semId)" 4
.IX Item "void sm_SemGive(sm_SemId semId)"
Gives the indicated semaphore, so that another task or process can take it.
.IP "void sm_SemEnd(sm_SemId semId)" 4
.IX Item "void sm_SemEnd(sm_SemId semId)"
This function is used to pass a termination signal to whatever task is
currently blocked on taking the indicated semaphore, if any.  It sets
to 1 the \*(L"ended\*(R" flag associated with this semaphore, so that a test for
\&\fIsm_SemEnded()\fR will return 1, and it gives the semaphore so that the
blocked task will have an opportunity to test that flag.
.IP "int sm_SemEnded(sm_SemId semId)" 4
.IX Item "int sm_SemEnded(sm_SemId semId)"
This function returns 1 if the \*(L"ended\*(R" flag associated with the
indicated semaphore has been set to 1; returns zero otherwise.  When
the function returns 1 it also gives the semaphore so that any other
tasks that might be pended on the same semaphore are also given an
opportunity to test it and discover that it has been ended.
.IP "void sm_SemUnend(sm_SemId semId)" 4
.IX Item "void sm_SemUnend(sm_SemId semId)"
This function is used to reset an ended semaphore, so that a restarted
subsystem can reuse that semaphore rather than delete it and allocate a
new one.
.IP "int sm_SemUnwedge(sm_SemId semId, int timeoutSeconds)" 4
.IX Item "int sm_SemUnwedge(sm_SemId semId, int timeoutSeconds)"
Used to release semaphores that have been taken but never released, possibly
because the tasks or processes that took them crashed before releasing them.
Attempts to take the semaphore; if this attempt does not succeed within
\&\fItimeoutSeconds\fR seconds (providing time for normal processing to be
completed, in the event that the semaphore is legitimately and temporarily
locked by some task), the semaphore is assumed to be wedged.  In any case,
the semaphore is then released.  Returns 0 on success, \-1 on any error.
.IP "void sm_SemDelete(sm_SemId semId)" 4
.IX Item "void sm_SemDelete(sm_SemId semId)"
Destroys the indicated semaphore.
.IP "sm_SemId sm_GetTaskSemaphore(int taskId)" 4
.IX Item "sm_SemId sm_GetTaskSemaphore(int taskId)"
Returns the \s-1ID\s0 of the semaphore that is dedicated to the private use of the
indicated task, or \s-1SM_SEM_NONE\s0 on any error.
.Sp
This function implements the concept that for each task there can
always be one dedicated semaphore, which the task can always use for its
own purposes, whose key value may be known a priori because the key of the
semaphore is based on the task's \s-1ID. \s0 The design of the function
rests on the assumption that each task's \s-1ID,\s0 whether a VxWorks task \s-1ID\s0
or a Unix process \s-1ID,\s0 maps to a number that is out of the range of all
possible key values that are arbitrarily produced by \fIsm_GetUniqueKey()\fR.
For VxWorks, we assume this to be true because task \s-1ID\s0 is a pointer to
task state in memory which we assume not to exceed 2GB; the unique key
counter starts at 2GB.  For Unix, we assume this to be true because
process \s-1ID\s0 is an index into a process table whose size is less than 64K;
unique keys are formed by shifting process \s-1ID\s0 left 16 bits and adding
the value of an incremented counter which is always greater than zero.
.IP "int sm_ShmAttach(int key, int size, char **shmPtr, int *id)" 4
.IX Item "int sm_ShmAttach(int key, int size, char **shmPtr, int *id)"
Attaches to a segment of memory to which tasks or processes residing in
a common system memory, but possibly multiple address spaces, all have
access.
.Sp
This function registers the invoking task or process as a user of the
shared memory segment identified by \fIkey\fR.  If \fIkey\fR is the constant value 
\&\s-1SM_NO_KEY,\s0 automatically sets \fIkey\fR to some unused key value.
If a shared memory segment identified by \fIkey\fR already exists, then
\&\fIsize\fR may be zero and the value of \fI*shmPtr\fR is ignored.
Otherwise the size of the shared memory segment must be provided
in \fIsize\fR and a new shared memory segment is created in a manner that is
dependent on \fI*shmPtr\fR: if \fI*shmPtr\fR is \s-1NULL\s0 then 
\&\fIsize\fR bytes of shared memory are dynamically acquired, allocated, and
assigned to the newly created shared memory segment; otherwise the
memory located at \fIshmPtr\fR is assumed to have been pre-allocated
and is merely assigned to the newly created shared memory segment.
.Sp
On success, stores the unique shared memory \s-1ID\s0 of the segment in \fI*id\fR
for possible future destruction, stores a pointer to the segment's
assigned memory in \fI*shmPtr\fR, and returns 1 (if the segment is newly
created) or 0 (otherwise).  Returns \-1 on any error.
.IP "void sm_ShmDetach(char *shmPtr)" 4
.IX Item "void sm_ShmDetach(char *shmPtr)"
Unregisters the invoking task or process as a user of
the shared memory starting at \fIshmPtr\fR.
.IP "void sm_ShmDestroy(int id)" 4
.IX Item "void sm_ShmDestroy(int id)"
Destroys the shared memory segment identified by \fIid\fR, releasing any
memory that was allocated when the segment was created.
.SS "\s-1PORTABLE\s0 MULTI-TASKING"
.IX Subsection "PORTABLE MULTI-TASKING"
.IP "int sm_TaskIdSelf( )" 4
.IX Item "int sm_TaskIdSelf( )"
Returns the unique identifying number of the invoking task or process.
.IP "int sm_TaskExists(int taskId)" 4
.IX Item "int sm_TaskExists(int taskId)"
Returns non-zero if a task or process identified by
\&\fItaskId\fR is currently running on the local processor, zero otherwise.
.IP "void *sm_TaskVar(void **arg)" 4
.IX Item "void *sm_TaskVar(void **arg)"
Posts or retrieves the value of the \*(L"task variable\*(R" belonging to the
invoking task.  Each task has access to a single task variable, initialized
to \s-1NULL,\s0 that resides in the task's private state; this can be convenient
for passing task-specific information to a signal handler, for example.  If
\&\fIarg\fR is non-NULL, then \fI*arg\fR is posted as the new value of the task's
private task variable.  In any case, the value of that task variable is
returned.
.IP "void sm_TaskSuspend( )" 4
.IX Item "void sm_TaskSuspend( )"
Indefinitely suspends execution of the invoking task or
process.  Helpful if you want to freeze an application
at the point at which an error is detected, then use a
debugger to examine its state.
.IP "void sm_TaskDelay(int seconds)" 4
.IX Item "void sm_TaskDelay(int seconds)"
Same as \fIsnooze\fR\|(3).
.IP "void sm_TaskYield( )" 4
.IX Item "void sm_TaskYield( )"
Relinquishes \s-1CPU\s0 temporarily for use by other tasks.
.IP "int sm_TaskSpawn(char *name, char *arg1, char *arg2, char *arg3, char *arg4, char *arg5, char *arg6, char *arg7, char *arg8, char *arg9, char *arg10, int priority, int stackSize)" 4
.IX Item "int sm_TaskSpawn(char *name, char *arg1, char *arg2, char *arg3, char *arg4, char *arg5, char *arg6, char *arg7, char *arg8, char *arg9, char *arg10, int priority, int stackSize)"
Spawns/forks a new task/process, passing it up to ten
command-line arguments.  \fIname\fR is the name of the
function (VxWorks) or executable image (\s-1UNIX\s0) to be executed 
in the new task/process.
.Sp
For \s-1UNIX, \s0\fIname\fR must be the name of some executable 
program in the \f(CW$PATH\fR of the invoking process.
.Sp
For VxWorks, \fIname\fR must be
the name of some function named in an application-defined private
symbol table (if \s-1PRIVATE_SYMTAB\s0 is defined) or the system symbol
table (otherwise).  If \s-1PRIVATE_SYMTAB\s0 is defined, the application must
provide a suitable adaptation of the symtab.c source file, which
implements the private symbol table.
.Sp
\&\*(L"priority\*(R" and \*(L"stackSize\*(R" are ignored under \s-1UNIX. \s0 Under VxWorks, if
zero they default to the values in the application-defined private
symbol table if provided, or otherwise to \s-1ICI_PRIORITY \s0(nominally 100)
and 32768 respectively.
.Sp
Returns the task/process \s-1ID\s0 of the new task/process on
success, or \-1 on any error.
.IP "void sm_TaskKill(int taskId, int sigNbr)" 4
.IX Item "void sm_TaskKill(int taskId, int sigNbr)"
Sends the indicated signal to the indicated task or process.
.IP "void sm_TaskDelete(int taskId)" 4
.IX Item "void sm_TaskDelete(int taskId)"
Terminates the indicated task or process.
.IP "void \fIsm_Abort()\fR" 4
.IX Item "void sm_Abort()"
Terminates the calling task or process.  If not called while \s-1ION\s0 is in
flight configuration, a stack trace is printed or a core file is written.
.IP "int pseudoshell(char *script)" 4
.IX Item "int pseudoshell(char *script)"
Parses \fIscript\fR into a command name and up to 10 arguments, then passes the
command name and arguments to \fIsm_TaskSpawn()\fR for execution.
The \fIsm_TaskSpawn()\fR function is invoked with priority and stack size both
set to zero, causing default values (possibly from an application-defined
private symbol table) to be used.  Tokens in 
\&\fIscript\fR are normally whitespace-delimited, but a token that is enclosed in
single-quote characters (') may contain embedded whitespace and may contain
escaped single-quote characters (\*(L"\e'\*(R").  On any parsing
failure returns \-1; otherwise returns the value returned by \fIsm_TaskSpawn()\fR.
.SH "USER'S GUIDE"
.IX Header "USER'S GUIDE"
.ie n .IP "Compiling an application that uses ""platform"":" 4
.el .IP "Compiling an application that uses ``platform'':" 4
.IX Item "Compiling an application that uses platform:"
Just be sure to \*(L"#include \*(R"platform.h"" at the top of each
source file that includes any platform function calls.
.ie n .IP "Linking/loading an application that uses ""platform"":" 4
.el .IP "Linking/loading an application that uses ``platform'':" 4
.IX Item "Linking/loading an application that uses platform:"
.Vb 1
\&    a.   In a Solaris environment, link with these libraries:
\&
\&             \-lplatform \-socket \-nsl \-posix4 \-c
\&
\&    b.   In a Linux environment, simply link with platform:
\&
\&             \-lplatform
\&
\&    c.   In a VxWorks environment, use
\&
\&             ld 1, 0, "libplatform.o"
\&
\&         to load platform on the target before loading applications.
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
gettimeofday(3C)