The "r" Package
These routines are meant to provide a low level mechanism to create and
accept connections. Although these routines are made public, their use is
NOT recommended. The conn package is the suggested means to create and
accept connections.
Library: karma
Link With: -lkarma
Functions
Tables
Functions
EXPERIMENTAL FUNCTION: subject to change without notice
flag
r_check_file_variants (CONST char *path, CONST char **extensions)
Test for variants of a filename.
Parameters:
- path :
The base pathname to check.
- extensions :
The list of extensions to append to path. This must be
terminated with a NULL pointer.
Returns: TRUE if one of the paths exists and is a file, else FALSE.
Multithreading Level: Unsafe
EXPERIMENTAL FUNCTION: subject to change without notice
pid_t
r_fork_and_execvp (int stdin_fd, int stdout_fd, int stderr_fd,
unsigned int num_close_fds, int *close_fds,
CONST char *file, char *CONST *argv, int *waitflags)
This function will fork and exec a new process in such as way as
to minimise virtual memory consumption. The traditional use of fork(2) can
consume large amounts of virtual memory under many operating systems (such
as Solaris and IRIX), especially when the calling process has large arrays
allocated. Some operating systems provide the vfork(2) call to work around
this, but vfork(2) is not always available and may in fact not provide the
Berkely vfork(2) semantics which preserved virtual memory. This function
will make use of whatever Operating System specific functions are available
in order to obtain the desired effect.
Parameters:
- stdin_fd :
The file descriptor which should become the standard input for
the child process.
- stdout_fd :
The file descriptor which should become the standard output for
the child process.
- stderr_fd :
The file descriptor which should become the standard error
output for the child process.
- num_close_fds :
The number of file descriptors to close in the child.
- close_fds :
The array of file descriptors to close in the child.
- file :
The file to execvp(3).
- argv :
The command-line arguments to pass to execvp(3).
- waitflags :
Special flags to pass to waitpid(2) are written here. If this
is NULL, the function will wait for the child process to terminate.
Returns: The child process ID on success, else -1.
Multithreading Level: Unsafe
int *
r_alloc_port (unsigned int *port_number, unsigned int retries,
unsigned int *num_docks)
This routine will allocate a Karma port for the module so that it
can operate as a server (able to receive network connections).
The routine will create a number of docks for one port. Each dock is an
alternative access point for other modules to connect to this port.
The close-on-exec flags of the docks are set such that the docks will
close on a call to execve(2V).
The docks are placed into non-blocking mode.
Parameters:
- port_number :
A pointer to the port number to allocate. The routine will
write the actual port number allocated to this address. This must point to
an address which lies on an int boundary.
- retries :
The number of succsessive port numbers to attempt to allocate
before giving up. If this is 0, then the routine will give up immediately
if the specified port number is in use.
- num_docs :
The number of docks allocated will be written here. This must
point to an address which lies on an int boundary.
Returns: A pointer to a statically allocated array of docks on success,
else NULL.
Multithreading Level: Unsafe
flag
r_close_dock (int dock)
This routine will close a dock. If the dock was the last open
dock for the port, then the entire port is closed and a new port may be
allocated.
Parameters:
- dock :
The dock to close.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
int
r_connect_to_port (unsigned long addr, unsigned int port_number,
flag *local)
Make a connection to a Karma port on some machine.
Parameters:
- addr :
The address of the machine to connect to. If the value of 0 is
supplied for the address, the connection is made to a Karma server running
on the local machine.
- port_number :
The port number to connect to.
- local :
If the connection is made to a port on the local host, then the
value TRUE will be written here, else the value FALSE will be written here.
Returns: The file descriptor of the opened connection on success, else -1.
Multithreading Level: Unsafe
Note: - The close-on-exec flags of the socket is set such that the socket
will close on a call to execve(2V).
EXPERIMENTAL FUNCTION: subject to change without notice
int
r_udp_alloc (unsigned int *port_number)
Create a UDP socket and bind to a random port number.
Parameters:
- port_number :
A pointer to the port number to bind to. If the port number
is 0, a random port number is bound to, and this value is updated with that
port number.
Returns: The file descriptor of the socket on success, else -1.
Multithreading Level: Unsafe
Note: - The close-on-exec flags of the socket is set such that the socket
will close on a call to execve(2V).
int
r_accept_connection_on_dock (int dock, unsigned long *addr, flag *local)
Accept a connection on a dock.
Parameters:
- dock :
The dock.
- addr :
The address of the host connecting to the dock will be written here.
- local :
If the connection is a local connection, then the routine will
write the value TRUE here, else it will write the value FALSE.
Returns: A connection on success, else -1.
Multithreading Level: Unsafe
flag
r_close_connection (int connection)
Close a connection.
Parameters:
- connection :
The connection to close.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
int
r_get_bytes_readable (int connection)
This routine will determine the minimum number of bytes readable
on a connection. There may be more bytes readable than indicated.
Parameters:
- connection :
The connection.
Returns: The number of bytes readable on success, else -1.
Multithreading Level: Unsafe
unsigned long
r_get_inet_addr_from_host (CONST char *host, flag *local)
Get the first listed Internet address of a hostname.
Parameters:
- host :
The hostname.
- local :
If the specified host is the local machine, then the routine will
write the value TRUE here, else it will write the value FALSE here. If
this is NULL, nothing is written here.
Returns: The Internet address on success (in host byte order), else 0.
Multithreading Level: Unsafe
iaddr
r_read (int fd, char *buf, uaddr nbytes)
This routine is similar to the system read(2) call, except
that the number of bytes requested is always returned (except on error or
closure). Hence, if the descriptor references a socket, the routine will
read as much data as was requested, rather than a lesser amount due to
packetisation or interrupted system calls.
Parameters:
- fd :
The file descriptor to read from. This descriptor must NOT be set to
non-blocking IO.
- buf :
The buffer in which to write the data.
- nbytes :
The number of bytes to read.
Returns: The number of bytes requested on success, the number of bytes
read on end of file (or closure) and -1 on error.
Multithreading Level: Unsafe
iaddr
r_write (int fd, CONST char *buf, uaddr nbytes)
This routine is similar to the system write(2) call, except
that the number of bytes requested is always returned (except on error).
Hence, if the descriptor references a socket, the routine will write as
much data as was requested, rather than a lesser amount due to
packetisation or interrupted system calls.
Parameters:
- fd :
The file descriptor to write to. This descriptor must NOT be set to
non-blocking IO.
- buf :
The buffer in which to write the data.
- nbytes :
The number of bytes to write.
Returns: The number of bytes requested on success, else -1 indicating
error.
Multithreading Level: Unsafe
Note: - The routine will force SIGPIPE to be ignored.
flag
r_test_input_event (int connection)
This routine will test if there is input activity on a
connection. This activity also covers the case of connection closure. The
connection descriptor must be given by connection .
Parameters:
This function takes no parameters
Returns: TRUE if there is some input activity, else FALSE.
Multithreading Level: Unsafe
Note: - This routine is only available on platforms which emulate the
communications facilities of Unix. It is NOT available on standard Unix
systems.
int
r_open_stdin (flag *disc)
Open the standard input.
Parameters:
- disc :
The routine will write the value TRUE here if the standard input is
a disc, else it will write FALSE.
Returns: The descriptor on success, else -1.
Multithreading Level: Unsafe
EXPERIMENTAL FUNCTION: subject to change without notice
int
r_open_stdin2 (unsigned int *type)
Open the standard input.
Parameters:
- disc :
The routine will write the type of the file here.
Returns: The descriptor on success, else -1.
Multithreading Level: Unsafe
CONST char *
r_getenv (CONST char *name)
Get the value of an environment variable.
Parameters:
- name :
The name of the environment variable.
Returns: A pointer to the value string if present, else NULL.
Multithreading Level: Unsafe
int
r_setenv (CONST char *env_name, CONST char *env_value)
This routine will provide a consistent interface to set
environment variables. This is necessary because the "standard" C library
routines: putenv or setenv (depending on the particular standard
C library supplied with the operating system) are in fact not standard.
Parameters:
- env_name :
The environment variable to create or change.
- env_value :
The string value to set the variable to.
Returns: 0 on success, else -1.
Multithreading Level: Unsafe
void
r_gethostname (char *name, unsigned int namelen)
This routine will determine the local hostname.
Parameters:
- name :
The hostname will be written here. It is guaranteed to be null
terminated.
- namelen :
The size of the buffer.
Returns: Nothing.
Multithreading Level: Unsafe
flag
r_get_fq_hostname (char *name, unsigned int namelen)
This routine will get the fully qualified local hostname.
Parameters:
- name :
The hostname will be written here. It is guaranteed to be null
terminated.
- namelen :
The size of the buffer.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
int
r_getppid ()
Get the parent process ID.
Parameters:
This function takes no parameters
Returns: The parent process ID.
Multithreading Level: Unsafe
int
r_open_file (CONST char *filename, int flags, int mode,
unsigned int *filetype, unsigned int *blocksize)
This routine will open a file. The file may be a regular disc
file, a named FIFO, a character special device, a Unix domain socket or a
TCP/IP connection (where supported). This routine provides an enhanced
interface to the open(2), socket(2) and connect(2) routines.
Parameters:
- filename :
The pathname of the file to open. This parameter has the same
meaning as the first parameter to open(2).
Filenames of the form: "//tcpIP/{hostname}:{port}" indicate a connection to
a TCP/IP port on host {hostname} with raw port number {port} is
requested.
- flags :
The access flags. This parameter has the same meaning as the second
parameter to open(2).
- mode :
If the file is created, the file protection modes will be determined
by the combination of the process umask and this value. This parameter
has the same meaning as the third parameter to open(2).
- filetype :
The type of the file will be written here. This may be NULL.
- blocksize :
The blocksize (in bytes) of the file will be written here (this
is only valid for a disc file). If the blocksize cannot be determined, the
value 0 will be written here. This may be NULL.
Returns: The file descriptor on success, else -1 and sets errno with
the error code.
Multithreading Level: Unsafe
int
r_create_pipe (int *read_fd, int *write_fd)
This routine will create an un-named pipe. This routine provides
an enhanced interface to the pipe(2) routine.
Parameters:
- read_fd :
The file descriptor corresponding to the read end of the pipe
will be written here.
- write_fd :
The file descriptor corresponding to the write end of the pipe
will be written here.
Returns: 0 on success, else -1 and sets errno with the error code.
Multithreading Level: Unsafe
EXPERIMENTAL FUNCTION: subject to change without notice
int
r_create_socketpair (int *fd1, int *fd2)
This routine will create an un-named pair of connected sockets.
This routine provides an enhanced interface to the socketpair(2)
routine.
Parameters:
- fd1 :
One end of the socketpair is written here.
- fd2 :
The other end of the socketpair is written here.
Returns: 0 on success, else -1 and sets errno with the error code.
Multithreading Level: Unsafe
EXPERIMENTAL FUNCTION: subject to change without notice
flag
r_get_fd_filetype (int fd, unsigned int *type)
Get filetype for a descriptor.
Parameters:
- fd :
The file descriptor.
- type :
The filetype is written here.
Returns: TRUE on success, else FALSE and an error message is displayed.
Multithreading Level: Unsafe
EXPERIMENTAL FUNCTION: subject to change without notice
flag
r_gethostbyaddr (char *name, unsigned int length, unsigned long addr)
Get hostname from Internet Address.
Parameters:
- name :
The hostname is written here.
- length :
The length of the hostname buffer.
- addr :
The Internet Address. If this is 0 the local hostname is given.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
EXPERIMENTAL FUNCTION: subject to change without notice
flag
r_set_nodelay (int fd)
Set the no-delay flag for a descriptor if appropriate.
Parameters:
- fd :
The file descriptor.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
EXPERIMENTAL FUNCTION: subject to change without notice
flag
r_create_exclusive_file (CONST char *filename, flag do_wait)
This routine will create a file, guaranteeing that no other
process (on any machine) created the file.
Parameters:
- filename :
The name of the file to create.
- do_wait :
If TRUE, the routine will wait until the file is created, or a
failure occurs.
Returns: TRUE if the file was created exclusively by the process, else
FALSE.
Multithreading Level: Unsafe
EXPERIMENTAL FUNCTION: subject to change without notice
flag
r_set_file_lock (int fd, flag lock, flag do_wait)
Grab or release the lock on a file.
Parameters:
- fd :
The file descriptor to (un)lock.
- lock :
If TRUE, the file is locked, else it is unlocked.
- do_wait :
If TRUE, the routine will wait until the lock is grabbed.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
EXPERIMENTAL FUNCTION: subject to change without notice
flag
r_send_fd (int conn_fd, int send_fd)
Send a file descriptor over a connection.
Parameters:
- conn_fd :
The connection file descriptor.
- send_fd :
The file descriptor to send.
Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe
EXPERIMENTAL FUNCTION: subject to change without notice
int
r_recv_fd (int conn_fd)
Receive a file descriptor over a connection.
Parameters:
- conn_fd :
The connection file descriptor.
Returns: The received file descriptor on success, else -1.
Multithreading Level: Unsafe
CONST char *
r_get_karmabase ()
Get the pathname of the installed runtime Karma.
Parameters:
This function takes no parameters
Returns: The pathname on success, else NULL.
Multithreading Level: Unsafe
int
r_get_service_number (CONST char *module_name)
This routine uses a hashing function to determine the service
number of a module.
Parameters:
- module_name :
The name of the module.
Returns: The service number.
Multithreading Level: Unsafe
CONST char *
r_get_host_from_display (CONST char *display)
This routine will get the hostname from a display string.
The syntax for the display string is the same as for the X Windows system
DISPLAY environmental variable.
Parameters:
- display :
The display string. If this is NULL, the host "unix" is returned.
Returns: A pointer to a statically allocated string which will contain the
host name on success, else NULL.
Multithreading Level: Unsafe
int
r_get_display_num_from_display (CONST char *display)
This routine will get the display number from a display string
(following the X Windows system syntax for the DISPLAY environmental
variable).
Parameters:
- display :
The display string. If this is NULL, the display number defaults
to 0.
Returns: The display number on success, else -1.
Multithreading Level: Unsafe
int
r_get_screen_num_from_display (CONST char *display)
This routine will get the screen number from a display string
(following the X Windows system syntax for the DISPLAY environmental
variable).
Parameters:
- display :
The display string. If this is NULL, the screen number defaults
to 0.
Returns: The display number on success, else -1.
Multithreading Level: Unsafe
int
r_get_def_port (CONST char *module_name, CONST char *display)
Get the default Karma port number for a module.
Parameters:
- module_name :
The module name.
- display :
The display string. The display number entry in the string is
also used to compute the port number. The syntax for this string is the
same as for the X Windows system DISPLAY environmental variable. If this is
NULL, the display number defaults to 0.
Returns: The default port number on success, else -1.
Multithreading Level: Unsafe
Note: - This routine does not resolve multiple port numbers residing on the
same machine and the same display number.
Tables
r_FILE_TYPES List of defined file types
| Type | Meaning
|
|
|
| KFTYPE_DISC | Disc (regular file)
|
| KFTYPE_CHARACTER | Character device
|
| KFTYPE_FIFO | FIFO (pipe)
|
| KFTYPE_UNIX_CONNECTION | Unix connection
|
| KFTYPE_LOCAL_tcpIP_CONNECTION | TCP/IP connection to local host
|
| KFTYPE_REMOTE_tcpIP_CONNECTION | TCP/IP connection to remote host
|
| KFTYPE_DIRECTORY | Directory
|
| KFTYPE_BLOCK | Block device
|
| KFTYPE_SOCKET | Socket
|
| KFTYPE_DANGLING_SYMLINK | Dangling symbolic link
|
Back to Karma Home Page
Contact: Richard Gooch
Web Development: Ariel Internet Services