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

r_check_file_variants	Test for variants of a filename.
r_fork_and_execvp	Fork and exec a process in a virtual memory efficient way.
r_alloc_port	Allocate a Karma port whic can receive connections.
r_close_dock	Close a dock.
r_connect_to_port	Make a connection to a Karma port on some machine.
r_udp_alloc	Create a UDP socket and bind to a random port number.
r_accept_connection_on_dock	Accept a connection on a dock.
r_close_connection	Close a connection.
r_get_bytes_readable	Get bytes readable on a connection.
r_get_inet_addr_from_host	Get the first listed Internet address of a hostname.
r_read	Read bytes from a file descriptor.
r_write	Write bytes to a file descriptor.
r_test_input_event	Test for activity on a connection.
r_open_stdin	Open the standard input.
r_open_stdin2	Open the standard input.
r_getenv	Get the value of an environment variable.
r_setenv	Set an environment variable.
r_gethostname	This routine will determine the local hostname.
r_get_fq_hostname	This routine will get the fully qualified local hostname.
r_getppid	Get the parent process ID.
r_open_file	Open a named file.
r_create_pipe	Create an un-named pipe.
r_create_socketpair	Create an un-named pair of connected sockets.
r_get_fd_filetype	Get filetype for a descriptor.
r_gethostbyaddr	Get hostname from Internet Address.
r_set_nodelay	Set the no-delay flag for a descriptor if appropriate.
r_create_exclusive_file	Exclusively create a file (typically for locking purposes).
r_set_file_lock	Grab or release the lock on a file.
r_send_fd	Send a file descriptor over a connection.
r_recv_fd	Receive a file descriptor over a connection.
r_get_karmabase	Get the pathname of the installed runtime Karma.
r_get_service_number	Get service number for a module.
r_get_host_from_display	Get the hostname in a display string.
r_get_display_num_from_display	Get display number from a display string.
r_get_screen_num_from_display	Get the screen number in a display string.
r_get_def_port	Get the default Karma port number for a module.

Tables

r_FILE_TYPES

List of defined file types

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:

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:

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:

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

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