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_alloc_portAllocate a Karma port whic can receive connections.
r_close_dockClose a dock.
r_connect_to_portMake a connection to a Karma port on some machine.
r_accept_connection_on_dockAccept a connection on a dock.
r_close_connectionClose a connection.
r_get_bytes_readableGet bytes readable on a connection.
r_get_inet_addr_from_hostGet the first listed Internet address of a hostname.
r_readRead bytes from a file descriptor.
r_writeWrite bytes to a file descriptor.
r_test_input_eventTest for activity on a connection.
r_open_stdinOpen the standard input.
r_getenvGet the value of an environment variable.
r_setenvSet an environment variable.
r_gethostnameThis routine will determine the local hostname.
r_get_fq_hostnameThis routine will get the fully qualified local hostname.
r_getppidGet the parent process ID.
r_open_fileOpen a named file.
r_create_pipeCreate an un-named pipe.
r_get_karmabaseGet the pathname of the installed runtime Karma.
r_get_service_numberGet service number for a module.
r_get_host_from_displayGet the hostname in a display string.
r_get_display_num_from_displayGet display number from a display string.
r_get_screen_num_from_displayGet the screen number in a display string.
r_get_def_portGet the default Karma port number for a module.


Functions


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:

Returns: A pointer to a statically allocated array of docks on success, else NULL.
Multithreading Level: Unsafe


void 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:

Returns: Nothing.
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:

Returns: The file descriptor of the opened connection on success, else -1.
Multithreading Level: Unsafe
Note:


int r_accept_connection_on_dock (int dock, unsigned long *addr, flag *local)

Accept a connection on a dock.

Parameters:

Returns: A connection on success, else -1.
Multithreading Level: Unsafe


flag r_close_connection (int connection)

Close a connection.

Parameters:

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:

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:

Returns: The Internet address on success (in host byte order), else 0.
Multithreading Level: Unsafe


int r_read (int fd, char *buf, int 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:

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


int r_write (int fd, CONST char *buf, int 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:

Returns: The number of bytes requested on success, else -1 indicating error.
Multithreading Level: Unsafe
Note:


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:


int r_open_stdin (flag *disc)

Open the standard input.

Parameters:

Returns: The descriptor on success, else -1.
Multithreading Level: Unsafe


char * r_getenv (CONST char *name)

Get the value of an environment variable.

Parameters:

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:

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:

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:

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:

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:

Returns: 0 on success, else -1 and sets errno with the error code.
Multithreading Level: Unsafe


char * r_get_karmabase ()

Get the pathname of the installed runtime Karma.

Parameters:

Returns: The pathname.
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:

Returns: The service number.
Multithreading Level: Unsafe


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:

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:

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:

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:

Returns: The default port number on success, else -1.
Multithreading Level: Unsafe
Note:


Contact: Richard Gooch
Web Development: Ariel Internet Services