Rover Server-Side Utility Interface

There should be a discussion of the global variables used by the server.

Name2Cmd // StatusMsg // Tcl_LoadLibrary // bartospace // copyString // createTclInterp // deleteTclInterp // emitData // emitLog // errorExit // escape_inplace // escape_shell_cmd // escape_tcl // escape_url // fatalError // ind // outstrBin // outstrC // outstrD // outstrL // outstrInit // outstrResize // outstrVC // outstrVD // outstrnC // outstrnD // rover_ctime // sendServerHeader // set_serverID // unescape_url // x2c

MIME-Compliant Base 64 Encoding and Decoding Library Routines: b64init // b64towrite // b64towriteend // b64fromreadinit // b64fromread // b64fromfgets // b64fromfgets

Fault-tolerant hash table functions stableHashInit // stableHashFetch // stableHashSetEntry

PUBLIC CMDtype Name2Cmd(char **name*)

Returns the CMDtype enumeration value associated with the name.

name is the string representation of the CMDtype enumeration.

Returns a statically allocated string.

PUBLIC char StatusMsg(Codes code*)

Returns the text string associated with a status code from the Codes enumeration.

code is value from the Codes enumeration.

Returns a statically allocated string.

PUBLIC void Tcl_LoadLibrary(char **name*)

Loads a Tcl file into the interpreter.

name is the name of the file to load.

No return value.

PUBLIC void bartospace(char **str*)

Unescapes any spaces (encoded as underscores `_') in str, inplace.

str is the string to unescape.

Returns the unescaped string.

PUBLIC char *copyString(char **string*)

Copies a string, allocating a new string.

string is the string to copy.

Returns a copy of the string. The user is responsible for freeing the string.

PUBLIC int createTclInterp()

Creates a Tcl interpreter, or if the Rover server is running standalone, looks for an interpreter in the tuple consisting of: <Host, user, service>. If an interpreter is created, it runs the local configuration file (which among other things should remove any commands we don't want downloaded programs to use), and then installs some Rover commands.

Returns 0, if a new interpreter was created; 1, if an existing interpreter was found, and -1, if an error occurred.

PUBLIC void deleteTclInterp()

Deletes the current interpreter (for the standalone server, also deletes the saved copy).

No return value.

PUBLIC void emitData()

Begins a data segment in the output buffer. The buffer previously must have been in the code segment mode, otherwise an errorExit will occur.

No return value.

PUBLIC void emitLog()

Begins a log suffix segment in the output buffer. The buffer previously must have been in the code or data segment mode, otherwise an errorExit will occur.

No return value.

PUBLIC void errorExit(char **msg*)

Indicates that the server has encountered a recoverable error. Sends an error object back to the client.

msg is the message to return in the error object.

No return value.

PUBLIC void escape_inplace(char **cmd*)

Escapes a TCL string in place (the string must be in a buffer with a minimum size of 2n). This table lists the characters that are escaped.

cmd is the string to be escaped.

No return value.

PUBLIC char *escape_shell_cmd(char **cmd*)

Caution should be exercised in using this command to escape strings that are going to be passed to the shell (e.g., using system). Potential security holes may still exist.

Escapes a string for the purpose of using it as a shell command by inserting a \ before any special shell characters. Allocates a new string if any escaping occurs. This table lists the characters that are escaped.

cmd is the string to be escaped.

If the string is escaped, returns a newly allocated string (the caller is responsible for freeing the string). Otherwise, the original string is returned.

PUBLIC char *escape_tcl(char **cmd*)

Escapes a string for the purpose of using it within Tcl by inserting a \ before any special Tcl characters. Allocates a new string if any escaping occurs. This table lists the characters that are escaped.

cmd is the string to be escaped.

If the string is escaped, returns a newly allocated string (the caller is responsible for freeing the string). Otherwise, the original string is returned.

PUBLIC char *escape_url(char **url*)

Escapes a URL for transmission by substituting a '%' followed by a two digit hexadecimal code for any characters that cannot be transmitted raw. This table lists the characters that are escaped. The inverse function is unescape_url.

url is the string to be escaped.

Returns the escaped string, the caller is responsible for freeing the string.

PUBLIC void fatalError(char **msg*)

Indicates that the server has encountered an unrecoverable error. Terminates the server.

msg is the message to print to stderr.

No return value.

PUBLIC int ind(char **str*, char ch)

Returns the index of ch in string str.

str is the string to search.
ch is the character to search for in str.

Returns the index of of the leftmost matching character, or -1 if the character is not found.

PUBLIC void outstrBin(void **bin, int count*)

Outputs count bytes of binary data from bin to the output buffer (the buffer must not be in code, data, or log suffix segment mode or an errorExit will occur).

bin is the binary data to be output.
count is the amount of data to output.

No return value.

PUBLIC void outstrC(char **string*)

Outputs string to the code segment of the output buffer (the buffer must be in code segment mode or an errorExit will occur).

string is the code to be output.

No return value.

PUBLIC void outstrD(char **string*)

Outputs string to the data segment of the output buffer (the buffer must be in data segment mode or an errorExit will occur).

string is the data to be output.

No return value.

PUBLIC void outstrL(char **host, int logID, HTOpStatus status*, char **operation*)

Generates a log suffix record and inserts the record into the log suffix segment of the output buffer (the buffer must be in log suffix segment mode or an errorExit will occur). The operation is not escaped.

host is the name of the client host that performed the operation.
logID is the client host's logID for the operation.
status is the status of the operation.
operation is the operation.

No return value.

PUBLIC void outstrInit(int size)

Initialize the output buffer and all related variables. The buffer will be at least size bytes in size.

size is the desired minimum buffer size.

No return value.

PUBLIC void outstrResize(int size)

Resizes the output buffer to be at least size bytes in size.

size is the desired minimum buffer size.

No return value.

PUBLIC void outstrVC(char **template, int count*, ...)

Outputs text to the code segement, applying substitutions first (the buffer must be in code segment mode or an errorExit will occur). count specifies the number of values (up to 9) provided for substitution in template. Each substition within template is specified as `%n', where n refers to the nth provided value.

template is the template to use to generate the code.
count is the number of values provided for substitution.
... are the values to substitute into the template.

No return value.

PUBLIC void outstrVD(char **template, int count*, ...)

Outputs text to the data segement, applying substitutions first (the buffer must be in data segment mode or an errorExit will occur). count specifies the number of values (up to 9) provided for substitution in template. Each substition within template is specified as `%n', where n refers to the nth provided value.

template is the template to use to generate the data.
count is the number of values provided for substitution.
... are the values to substitute into the template.

No return value.

PUBLIC void outstrnC(char **string, int count*)

Outputs count bytes of string to the code segment of the output buffer (the buffer must be in code segment mode or an errorExit will occur).

string is the code to be output.
count is the number of bytes to be output.

No return value.

PUBLIC void outstrnD(char **string, int count*)

Outputs count bytes of string to the data segment of the output buffer (the buffer must be in data segment mode or an errorExit will occur).

string is the code to be output.
count is the number of bytes to be output.

No return value.

PUBLIC char *rover_ctime(time_t **stamp*)

Similar to the C library function ctime, converts a time_t time into it's ASCII representation (e.g., "Wed Jun 30 21:49:08 1993"). Differs in that it strips the trailing newline.

time is the time_t time.

Returns the ASCII representation of time in a statically allocated string.

PUBLIC int sendServerHeader(int **extra*)

Constructs and sends a status header to the client, followed by the output buffer and any dependency information. Sets extra to the number of bytes of dependency vector information sent to the client.

extra is a pointer to an integer, which this procedure sets to the number of bytes of dependency vector information sent to the client.

Returns the number of bytes sent to the client from the output buffer.

PUBLIC void set_serverID()

Sets the server's unique server identifier.

PUBLIC void unescape_url(char **from, char to)

Unescapes an escaped URL, substituting the equivalent ASCII character for three-character `%XX' hexadecimal sequences. This reverses the escaping performed by escape_url This table lists the affected characters.

from is the source (escaped) string.
to is the target (unescaped) string. The caller is responsible for ensuring that the target string is large enough to hold the unescaped source string.

No return value.

PUBLIC char x2c(char **hex*)

Returns the ASCII character associated with a 2-digit hexadecimal value.

hex is the ASCIII-encoded 2-digit hexadecimal value.

Returns the ASCII character representation of hex.

MIME-Compliant Base 64 Encoding and Decoding Library Routines

Routines for writing and reading MIME-compliant base 64 encoded data to and from a stream.

To encode a stream, first call b64toinit to initialize the encoder. Then call b64towrite to write and encode data to the stream. Finish by calling b64towriteend (this operation does not close file).

To decode a stream, first call b64fromreadinit on an open stream to initialize the decoder. Then call b64fromread and/or b64fromfgets (similar in function to the fread and fgets functions to read blocks or lines. Finish by calling b64fromend when done.

PUBLIC void b64toinit(struct b64tostate *s)

Initializes an encoder structure to begin encoding.

s is the encoder structure to be initialized.

No return value.

PUBLIC size_t b64towrite(char **ptr, size_t n, FILE f, struct b64tostate *s)

Writes n bytes from ptr to the stream f, encoded in base 64.

ptr is a pointer to the data to be encoded and writen to the stream.
n is the number of bytes to write.
f is the stream to write the encoded data to.
s is an initialized encoder structure.

No return value.

PUBLIC size_t b64towriteend(FILE f, struct b64tostate s)

Flushes any leftover bytes to the stream f, then adds an extra newline for luck. Does not close the stream.

f is the stream to flush.
s is an initialized encoder structure.

No return value.

PUBLIC void b64fromreadinit(FILE f,struct b64tostate s)

Initializes a decoder structure to decoding.

f is the stream to decode from.
s is the decoder structure to be initialized.

No return value.

PUBLIC size_t b64fromread(char **buf, size_t n, FILE f, struct b64fromstate *s)

Reads and decodes up to n bytes from stream f, placing them in buf.

f is the stream to decode from.
s is an initialized decoder structure.

Returns the number of bytes actually read.

PUBLIC size_t b64fromfgets(char **buf, size_t n, FILE f, struct b64fromstate *s)

Reads and decodes up to n bytes from stream f, placing them in buf. Stops if a newline is read.

f is the stream to decode from.
s is an initialized decoder structure.

Returns the number of bytes actually read.

PUBLIC void b64fromend(struct b64fromstate *s)

Clean up after decoding.

s is an initialized decoder structure.

No return value.

Fault-Tolerant RDO Functions

These Standalone Daemon server functions implement stable hash table services. These procedures can be used to create long-running RDOs that will survive (reasonable) failures of the server process or machine.

PUBLIC int stableHashInit(char **tableName*)

Declares and initializes a stable hash table named tableName and logs the information to a stable log. Upon restart after a server failure, the stable hash table will be recreated and reinitialized. Note: There is a 256 character limit on table names.

tableName is the name of the stable hash table to be created.

Returns 1 if the table was created; otherwise, returns 0.

PUBLIC char *stableHashFetch(char **tableName*, char **entryName*)

Fetches the entry with the key entryName in the stable hash table tableName.

tableName is the name of the stable hash table.
entryName is the name of the key to search for.

Returns the entry if one is found; otherwise, returns NULL.

PUBLIC int stableHashSetEntry(char **tableName*, char **entryName*, char **data, int size*, char ***old*)

Creates or updates the entry with the key entryName in the stable hash table tableName.

tableName is the name of the stable hash table.
entryName is the name of the key to create or update.
data is the data to be saved.
size is the size of the data to be saved.
old is set by the function to the old data value, if the entry is updated instead of being created.

Returns 0 if the entry was successfully updated; otherwise, returns -1.

PUBLIC void stableLogOutput()

Saves the current output buffer to the stable log.

No return value.

Rover Server-Side Utility Interface

PUBLIC CMDtype Name2Cmd(char *name)

PUBLIC char *StatusMsg(Codes code)

PUBLIC void Tcl_LoadLibrary(char *name)

PUBLIC void bartospace(char *str)

PUBLIC char *copyString(char *string)

PUBLIC int createTclInterp()

PUBLIC void deleteTclInterp()

PUBLIC void emitData()

PUBLIC void emitLog()

PUBLIC void errorExit(char *msg)

PUBLIC void escape_inplace(char *cmd)

PUBLIC char *escape_shell_cmd(char *cmd)

PUBLIC char *escape_tcl(char *cmd)

PUBLIC char *escape_url(char *url)

PUBLIC void fatalError(char *msg)

PUBLIC int ind(char *str, char ch)

PUBLIC void outstrBin(void *bin, int count)

PUBLIC void outstrC(char *string)

PUBLIC void outstrD(char *string)

PUBLIC void outstrL(char *host, int logID, HTOpStatus status, char *operation)

PUBLIC void outstrInit(int size)

PUBLIC void outstrResize(int size)

PUBLIC void outstrVC(char *template, int count, ...)

PUBLIC void outstrVD(char *template, int count, ...)

PUBLIC void outstrnC(char *string, int count)

PUBLIC void outstrnD(char *string, int count)

PUBLIC char *rover_ctime(time_t *stamp)

PUBLIC int sendServerHeader(int *extra)

PUBLIC void set_serverID()

PUBLIC void unescape_url(char *from, char *to)

PUBLIC char x2c(char *hex)

MIME-Compliant Base 64 Encoding and Decoding Library Routines

PUBLIC void b64toinit(struct b64tostate *s)

PUBLIC size_t b64towrite(char *ptr, size_t n, FILE *f, struct b64tostate *s)

PUBLIC size_t b64towriteend(FILE *f, struct b64tostate *s)

PUBLIC void b64fromreadinit(FILE *f,struct b64tostate *s)

PUBLIC size_t b64fromread(char *buf, size_t n, FILE *f, struct b64fromstate *s)

PUBLIC size_t b64fromfgets(char *buf, size_t n, FILE *f, struct b64fromstate *s)

PUBLIC void b64fromend(struct b64fromstate *s)

Fault-Tolerant RDO Functions

PUBLIC int stableHashInit(char *tableName)

PUBLIC char *stableHashFetch(char *tableName, char *entryName)

PUBLIC int stableHashSetEntry(char *tableName, char *entryName, char *data, int size, char **old)

PUBLIC void stableLogOutput()

PUBLIC CMDtype Name2Cmd(char **name*)

PUBLIC char StatusMsg(Codes code*)

PUBLIC void Tcl_LoadLibrary(char **name*)

PUBLIC void bartospace(char **str*)

PUBLIC char *copyString(char **string*)

PUBLIC void errorExit(char **msg*)

PUBLIC void escape_inplace(char **cmd*)

PUBLIC char *escape_shell_cmd(char **cmd*)

PUBLIC char *escape_tcl(char **cmd*)

PUBLIC char *escape_url(char **url*)

PUBLIC void fatalError(char **msg*)

PUBLIC int ind(char **str*, char ch)

PUBLIC void outstrBin(void **bin, int count*)

PUBLIC void outstrC(char **string*)

PUBLIC void outstrD(char **string*)

PUBLIC void outstrL(char **host, int logID, HTOpStatus status*, char **operation*)

PUBLIC void outstrVC(char **template, int count*, ...)

PUBLIC void outstrVD(char **template, int count*, ...)

PUBLIC void outstrnC(char **string, int count*)

PUBLIC void outstrnD(char **string, int count*)

PUBLIC char *rover_ctime(time_t **stamp*)

PUBLIC int sendServerHeader(int **extra*)

PUBLIC void unescape_url(char **from, char to)

PUBLIC char x2c(char **hex*)

PUBLIC size_t b64towrite(char **ptr, size_t n, FILE f, struct b64tostate *s)

PUBLIC size_t b64towriteend(FILE f, struct b64tostate s)

PUBLIC void b64fromreadinit(FILE f,struct b64tostate s)

PUBLIC size_t b64fromread(char **buf, size_t n, FILE f, struct b64fromstate *s)

PUBLIC size_t b64fromfgets(char **buf, size_t n, FILE f, struct b64fromstate *s)

PUBLIC int stableHashInit(char **tableName*)

PUBLIC char *stableHashFetch(char **tableName*, char **entryName*)

PUBLIC int stableHashSetEntry(char **tableName*, char **entryName*, char **data, int size*, char ***old*)