intro(3) CLIX intro(3)
NAME
intro - Introduction to functions and libraries
DESCRIPTION
This section describes functions found in various libraries, other than
those that directly invoke CLIX system primitives. The system primitives
are described in Section 2 of this manual. Section 3 of this manual
describes the following types of functions:
⊕ Functions that compose, in part, the Standard C Library, libc, that is
automatically loaded by the C compiler. The functions that compose the
rest of libc are described in Section 2. The link editor, ld, searches
this library under the -lc flag. A shared library version of libc can
be searched using the -lc_s flag, resulting in smaller a.out files.
Declarations for some of these functions may be obtained from #include
files indicated on the appropriate pages. (These functions were
described in section 3C in previous versions of CLIX reference
manuals.)
⊕ Functions that compose the ``standard I/O package'' (see stdio(3)).
These functions are in the libc library mentioned above. Declarations
for these functions may be obtained from the #include file <stdio.h>.
(These functions were described in section 3S in previous versions of
CLIX reference manuals.)
⊕ Functions that compose, in part, Berkeley Software Distribution (BSD)
Library, libbsd. The functions that compose the rest of libbsd are
described in Section 2. These functions are not automatically loaded
by the C compiler; however, the link editor, ld, searches this library
under the -lbsd flag. (These functions were described in section 3B in
previous versions of CLIX reference manuals.)
⊕ Functions that compose the Intergraph Network Library, libinc. They
are not automatically loaded by the C compiler; however, the link
editor ld searches this library under the -linc flag. (These functions
were described in section 3N in previous versions of CLIX reference
manuals.)
⊕ Functions that compose the Remote Procedure Call (RPC) and External
Data Representation (XDR) package. These functions are in the libbsd
library mentioned above. (These functions were described in section 3R
in previous versions of CLIX reference manuals.)
⊕ Functions that compose, in part, the Intergraph Extensions Library,
libix. The functions that compose the rest of libix are described in
Section 2. These functions compose the asynchronous I/O package. They
are not automatically loaded by the C compiler; however, the link
editor, ld, searches this library under the -lix flag. (These
functions were described in section 3A in previous versions of CLIX
2/94 - Intergraph Corporation 1
intro(3) CLIX intro(3)
reference manuals.)
⊕ Functions that compose the Intergraph extensions to the FORTRAN
intrinsic function library, libf. These functions are automatically
available to the FORTRAN programmer and require no special invocation
of the compiler. (These functions were described in section 3F in
previous versions of CLIX reference manuals.)
The Synchronous/Asynchronous I/O Library
This section describes the functions found in the synchronous/asynchronous
I/O (XIO) library, libix. The link editor, ld, searches this library
under the -lix flag.
The XIO system controls synchronous and asynchronous I/O requests to XIO
drivers in the CLIX kernel (see the Section 7 reference manual entries).
Although any request to an XIO driver may be asynchronous, only requests
that could block are available as asynchronous requests.
Associated with each asynchronous request is an event flag number (efn),
and an XIO completion status block (xiosb structure) passed as part of the
parameter list. The event flag number is used to track the completion of
the asynchronous request; the xiosb structure is updated with the
completion information for the asynchronous request.
Two functions in the library manage allocation of event flag numbers. The
xio_allocef() function allocates an unused event flag number (an integer
between 0 and 31, inclusive). The xio_deallocef() function frees a
previously allocated event flag number.
The xiosb structure, allocated for each asynchronous request, is shown
below and is defined in the <sys/xio/xio.h> include file:
struct xiosb {
int status; /* completion error status */
int xfcnt; /* size of transferred data */
int seqnum; /* sequence number of event */
};
The members of the xiosb structure are described as follows:
status The error value returned from the XIO driver. Possible return
values are listed in the <sys/xio/xerr.h> include file. A value
of 0 indicates no error occurred.
xfcnt The total number of bytes of data transferred by the XIO driver.
However, in some cases, a parameter may be returned in this
member. See the reference manual entry for each request to
determine the exact use of this member.
seqnum This member determines the order of completion for asynchronous
2 Intergraph Corporation - 2/94
intro(3) CLIX intro(3)
requests. The XIO system sets this member to a value of one
greater than the previously completed asynchronous request.
The XIO system in the CLIX kernel provides a 32-bit mask, the event flag
mask, to monitor the completion of asynchronous requests. Initially, all
bits in the event flag mask are set. When an asynchronous request is
issued, the XIO system clears the bit corresponding to the event flag
number for the request. When an asynchronous request has completed, the
XIO system sets the bit corresponding to the event flag number of the
completed request. The user may determine the completion of an
asynchronous request by checking its corresponding bit in the event flag
mask.
In addition to bits in the event flag mask being altered by the invocation
and completion of asynchronous requests, the xio_clref() and xio_setef()
also modify the event flag mask. The xio_clref() function clears bits in
the event flag mask as specified in the calling argument, and the
xio_setef() function sets bits in the event flag mask as specified in the
calling argument.
Four functions allow a process to act on the current state of the event
flag mask (and thus the completion state of the associated asynchronous
requests). The functions are described as follows:
xio_readef() Return the event flag mask. Cleared bits in the mask
possibly represent asynchronous requests that have not
completed. The process is responsible for knowing which
bits in the event flag mask are currently used by an
asynchronous request.
xio_waitfr() Return control to the caller only when the bit in the event
flag mask corresponding to the event flag number specified
in the call is set. The call, in effect, waits for the
completion of an outstanding asynchronous request.
xio_wflor() Return control to the caller when any of the bits in the
event flag mask that correspond to set bits in the mask
specified by the call are set. The call, in effect, waits
for one of the outstanding asynchronous requests to
complete.
xio_wfland() Return control to the caller when all bits in the event
flag mask that correspond to all set bits in the mask
specified by the call are set. This provides a mechanism
for a process to wait for the completion of many
outstanding asynchronous requests.
In addition to the above functions, xio_notify() notifies a process that
an asynchronous request has been completed. The notification is either by
a signal, by alternation of an integer pair in the process's data space,
or both. See xio_notify(3) for more information.
2/94 - Intergraph Corporation 3
intro(3) CLIX intro(3)
Examples
The following example uses an asynchronous request to receive data from a
device. The DEV device is fictitious and used with this example only.
#include <sys/xio/xio.h>
#include <sys/xio/xerr.h>
#include <errno.h>
...
int efn;
struct xiosb xiosb;
char buffer[SIZE];
...
/*
* Allocate unique event number
*/
if (xio_allocef(&efn) == 0) {
printf("no more events\n");
exit(1);
}
/*
* Issue request to device DEV
*/
if (DEV_readnw(buffer, SIZE, &xiosb, efn) == XIO_FAILURE) {
printf("request failed, errno = %d\n", errno);
exit(1);
}
/*
* At this point, the process is free to do any other type
* of requests or processing. When the "DEV_readnw" event
* completes, the request will be queued until the process
* polls the system or waits for this event.
*
* For the purpose of our example, the program will wait for
* this event.
*/
xio_waitfr(efn);
if (xiosb.status) {
printf("bad request status, status = %d\n", xiosb.status);
exit(1);
}
printf("total amount of data returned = %d\n", xiosb.xfcnt);
...
Note: Since XIO devices are not in the CLIX name space, access to them
4 Intergraph Corporation - 2/94
intro(3) CLIX intro(3)
cannot be restricted.
The Berkeley Software Distribution (BSD) Library
This section describes functions found in the Berkeley Software
Distribution (BSD) library, libbsd.a, that do not directly invoke CLIX
system primitives. The link editor, ld, searches this library under the
-lbsd flag. The list of functions is as follows:
Name Appears on Page Description
____________________________________________________________________
bcmp bstring(3) bit and byte string operations
bcopy bstring(3) bit and byte string operations
bzero bstring(3) bit and byte string operations
dbm_clearerr ndbm(3) database functions
dbm_close ndbm(3) database functions
dbm_delete ndbm(3) database functions
dbm_error ndbm(3) database functions
dbm_fetch ndbm(3) database functions
dbm_firstkey ndbm(3) database functions
dbm_nextkey ndbm(3) database functions
dbm_open ndbm(3) database functions
dbm_store ndbm(3) database functions
endhostent gethostbyname(3) get network host entry
endnetent getnetent(3) get network entry
endprotoent getprotoent(3) get protocol entry
endservent getservent(3) get service entry
ffs bstring(3) bit and byte string operations
gethostbyaddr gethostbyname(3) get network host entry
gethostbyname gethostbyname(3) get network host entry
gethostent gethostbyname(3) get network host entry
getnetbyaddr getnetent(3) get network entry
getnetbyname getnetent(3) get network entry
getnetent getnetent(3) get network entry
getprotobyname getprotoent(3) get protocol entry
getprotobynumber getprotoent(3) get protocol entry
getprotoent getprotoent(3) get protocol entry
getservbyname getservent(3) get service entry
getservbyport getservent(3) get service entry
getservent getservent(3) get service entry
htonl byteorder(3) convert values between host
and network byte order
htons byteorder(3) convert values between host
and network byte order
index string(3) string operations
inet_addr inet(3) Internet address manipulation
functions
Internet address manipulation
functions
2/94 - Intergraph Corporation 5
intro(3) CLIX intro(3)
inet_lnaof inet(3)
6 Intergraph Corporation - 2/94
intro(3) CLIX intro(3)
inet_makeaddr inet(3) Internet address manipulation
functions
inet_netof inet(3) Internet address manipulation
functions
inet_network inet(3) Internet address manipulation
functions
insque insque(3) insert/remove element from a
queue
ntohl byteorder(3) convert values between host
and network byte order
ntohs byteorder(3) convert values between host
and network byte order
random random(3) better random number generator
rcmd rcmd(3) functions for returning a
stream to a remote command
remque insque(3) insert/remove element from a
queue
rexec rexec(3) return stream to a remote
command
rindex string(3) string operations
rresvport rcmd(3) functions for returning a
stream to a remote command
ruserok rcmd(3) functions for returning a
stream to a remote command
sethostent gethostbyname(3) get network host entry
setnetent getnetent(3) get network entry
setprotoent getprotoent(3) get protocol entry
setservent getservent(3) get service entry
srandom random(3) better random number generator
Intergraph Network Core (INC)
This section describes the available networking modules and functions
provided with the Intergraph Network Core (INC) product. The
communications library provided with the INC product contains a number of
functionally separate modules. The following modules are available:
fmu The File Management Utility (provides an interface for file
transfer)
sni The Simple Network Interface
clh The clearinghouse
When a program is linked, the following syntax should be used:
cc object ... -linc -ldevi_s
RPC/XDR/NIS Service Functions and Protocols
2/94 - Intergraph Corporation 7
intro(3) CLIX intro(3)
This section describes functions that define access functions to the
standard Remote Procedure Call (RPC) and Network Information Service (NIS)
services. To access these functions, link with libyp.a for NIS services,
and libbsd.a for RPC information. The list of standard services is as
follows:
Name Appears on Page Description
_________________________________________________________
getdomain getdomain(3) get NIS domain name
getrpcent getrpcent(3) get RPC entry name
getrpcport getrpcport(3) get RPC port number
ypclnt ypclnt(3) NIS protocol
yppasswd yppasswd(3) update users passwd in NIS
FILES
$LIBDIR
$LIBDIR/libc.a
$LIBDIR/libc_s.a
/shlib/libc_s
The shared version of the Standard C library, libc
/usr/lib/libbsd.a
The Berkeley Software Distribution (BSD) Library
/usr/lib/libinc.a
The Intergraph Network Library
/usr/lib/libix.a
The Synchronous/Asynchronous I/O Library
DIAGNOSTICS
General
Functions in the C Library (3) may return the conventional values 0 or
+HUGE (the largest-magnitude single-precision floating-point numbers; HUGE
is defined in the <math.h> header file) when the function is undefined for
the given arguments, or when the value is not representable. In these
cases, the external variable, errno (see intro(2) ) is set to the value
EDOM or ERANGE.
INC
If the request is successful, a null pointer is returned. Otherwise, a
pointer to an error message is returned.
WARNINGS
8 Intergraph Corporation - 2/94
intro(3) CLIX intro(3)
General
Many of the functions in the libraries call and/or refer to other
functions and external variables described in this section and in
Section 2. If a program inadvertently defines a function or
external variable with the same name, the presumed library version
of the function or external variable may not be loaded. The lint
program checker reports name conflicts of this kind as ``multiple
declarations'' of the names in question. Definitions for the
Standard C Library are checked automatically. Other definitions
can be included by using the -l flag. Using lint is highly
recommended.
Synchronous/Asynchronous I/O Library
If any Environ V Library functions for graphics or graphics device
interfaces are used, the XIO system is controlled by Environ V
functions. For information on using XIO devices with Environ V
functions, see Setup_system_event(3E).
Because an event flag number is used to track an asynchronous
request completion, no two outstanding requests should use the same
event flag number at the same time.
RELATED INFORMATION
Commands: cc(1), ld(1), ar(1), lint(1), nm(1), ld(1)
Functions: intro(2), stdio(3), xio_allocef(3), xio_readef(3),
xio_notify(3), xio_waitfr(3)
Section 7 reference manual entries
CLIX Programming Guide
2/94 - Intergraph Corporation 9