- 2 -

Client/Server Tutorial

Servers are used to perform specialized functions and form the basis of centralized object management. There are many standard servers delivered with Amoeba. These include the Bullet File Server, the Soap Directory Server, the Virtual Disk Server and the Run Server (which does load balancing at process creation-time), among many others. To develop basic applications and port utilities from other operating systems the standard servers are usually adequate. However for some applications this is not enough. This section gives an indication of how to write your own servers and clients and points out some of the pitfalls to avoid.

Servers normally have a fixed set of commands that they accept. They sit in a loop accepting commands, executing them and sending a reply. To simplify the client's interaction with a server it calls a procedure, known as a stub. This packages the command and data in the manner required by the server and sends it to the server using a remote procedure call (RPC) and then awaits a reply. The procedure also unpacks any data in the reply and hands it back to the client. The stub allows details of the server interface and the possible byte-order differences between client and server's processors to be hidden from the programmer. Below is a description of how to write servers, their stubs and the clients that use them.

The following description of how to write clients and servers begins by showing what the C code actually looks like for a client/server interface. The reason for this is purely educational. In fact it is seldom necessary to write the server loop and client stub code yourself. AIL (the Amoeba Interface Language) can be used to generate this code automatically. The implementation of the commands must be written by the programmer of course. One advantage of this is that if the RPC interface ever changes, then recompiling the client/server interface with AIL will probably be sufficient to port the server to the new RPC interface. Another advantage is that it is in principle easier to write a specification of the interface in AIL than to write the code for every interface stub.

Before writing servers and clients it is important to understand the system of F-boxes described in many of the papers about Amoeba. These have been implemented in software. The idea of the F-box is that it prevents someone starting a server which intercepts RPCs intended for some other (important) server by deliberately listening to the same port.

The F-box mechanism works as follows. When a getreq call is done it listens to the get-port for the server. This is a port known only to the server. The server's kernel passes this port through the routine priv2pub(L) to encrypt the port. The result is known as the put-port and the kernel accepts requests sent to the put-port. Priv2pub is a one-way function so it is practically impossible to deduce the get-port given the put-port.

Before doing a getreq the server needs to publish the put-port through which it can be found by clients. Therefore it also passes the get-port through priv2pub and publishes the result in the directory server in a place accessible to its clients. In principle it is not possible to listen for requests on the public port unless the get-port is known.
This actually provides very little security if it is possible for someone to boot modified Amoeba kernels on your network. They can add a primitive for listening to put-ports or modify a kernel binary to avoid the conversion of get-port to put-port when getreq is called. The same deficiency occurs if the F-box is implemented in hardware and it is possible to connect to the network without an intervening F-box.

#define NTHREADS
#define STACKSZ
#define SERVER_CAP
#define REQ_BUFSZ

5
0x4000
"/home/this_server/default"
(2*sizeof(long))

#define DO_SWAP
#define DO_NOTHING

UNREGISTERED_FIRST_COM
(DO_SWAP+1)

#define RGT_DONOTHING ((rights_bits)0x01) #define RGT_DOSWAP ((rights_bits)0x02)

#include "amoeba.h"
#include "stderr.h"
#include "module/rnd.h"
#include "module/name.h" #include "this_server.h"

{

capability put_cap;
errstat err;
int i;

/* initialize the server's get capability */
uniqport(&get_cap.cap_port);
uniqport(&check_field);
if (prv_encode(&get_cap.cap_priv, (objnum) 0,
(rights_bits) 0xFF, &check_field) != 0) {
printf("Could not initialize capability\n");
exit(1);
}
priv2pub(&get_cap.cap_port, &put_cap.cap_port);
put_cap.cap_priv = get_cap.cap_priv;

/* publish put capability in directory server */
if ((err = name_append(SERVER_CAP, &put_cap)) != STD_OK) {
printf("Cannot append to %s: %s\n", SERVER_CAP,
err_why(err));
exit(1);
}
/* start the NTHREADS server_loop threads */
for (i = 0; i < NTHREADS-1; i++)
if (!thread_newthread(server_loop,
STACKSZ, (char *) 0, 0))
printf("Cannot start server thread\n");
server_loop();
/*NOTREACHED*/

}

#include "amoeba.h"
#include "cmdreg.h"
#include "stderr.h"
#include "this_server.h"
extern capability get_cap;
extern errstat do_swap(), do_nothing();
/*ARGSUSED*/
void
server_loop(param, size)
char * param;
int size;
{
header hdr;
char reqbuf[REQ_BUFSZ], repbuf[REQ_BUFSZ];
bufsize n;
for (;;) {
hdr.h_port = get_cap.cap_port;

n = getreq(&hdr, reqbuf, REQ_BUFSZ);
if (ERR_STATUS(n)) {
printf("getreq failed: %s\n", err_why((errstat) n));
exit(1);
}
switch (hdr.h_command) {
case DO_SWAP:
hdr.h_status = do_swap(&hdr, reqbuf, n, repbuf);
break;
case DO_NOTHING:
hdr.h_status = do_nothing(&hdr, reqbuf, n, repbuf);
break;
default:
hdr.h_status = STD_COMBAD;
hdr.h_size = 0;
break;
}
putrep(&hdr, repbuf, hdr.h_size);

}

}

#include "amoeba.h"
#include "cmdreg.h"
#include "stderr.h"
#include "module/prv.h"
extern port check_field;
errstat
check_cap(priv, required_rights) private * priv;
rights_bits required_rights;
{
rights_bits rights;
if (prv_number(priv) != 0 ||

}

prv_decode(priv, &rights, &check_field) != 0)
return STD_CAPBAD;
if ((rights & required_rights) != required_rights)
return STD_DENIED;
return STD_OK;

{

char * p;
char * q;
long val1, val2;
errstat err;
hdr->h_size = 0; /* in case of error */
if ((err = check_cap(&hdr->h_priv, RGT_DOSWAP)) != STD_OK)
return err;
q = req;
p = rep;

/* get the two longs from the request buffer */
q = buf_get_long(q, req + reqsz, &val1);
q = buf_get_long(q, req + reqsz, &val2);

/* if q is 0 then the request buffer did not contain two longs! */
if (q == 0)
return STD_ARGBAD;

/* now put them into the reply buffer in reverse order */
p = buf_put_long(p, rep + REQ_BUFSZ, val2);
p = buf_put_long(p, rep + REQ_BUFSZ, val1);

/* if p is 0 then the buffer of the server is too small */
if (p == 0)
return STD_SYSERR;
hdr->h_size = p - rep;
return STD_OK;

}

- 7 -

null pointer. Thus if any of the calls returns a null pointer then all subsequent calls will also do so and the error test need only be done once at the end of a series of get or put calls.

In this example the server expects two longs in the request buffer. It swaps them and inserts the result into the reply buffer using buf_put_long and returns the total size of the reply buffer to the server_loop which sends the reply.

It is now time to consider what is needed on the client side. It is possible to write a client program which knows all about the data formats that the server expects. However it is almost certainly simpler to provide the client with single routine to call which hides the details of marshaling the data and sending it to the server. One reason for doing this is that the implementation of the RPC is then hidden from the client program and any of the planned changes to that interface need only be modified in a few stub routines and the programs should then continue to function after recompilation. If AIL is used then recompilation of the sources should be sufficient.
A stub routine for DO_SWAP might look like the following.

#include "amoeba.h"
#include "cmdreg.h"
#include "stderr.h"
#include "module/buffers.h"
#include "this_server.h"
errstat
swap_longs(svr, val1, val2)
capability * svr;
long * val1;
long * val2;
{
header hdr;
bufsize t;
char buf[REQ_BUFSZ];
char * p;
hdr.h_port = svr->cap_port;
hdr.h_priv = svr->cap_priv;
hdr.h_command = DO_SWAP;
p = buf_put_long(buf, buf + REQ_BUFSZ, *val1);
p = buf_put_long(p, buf + REQ_BUFSZ, *val2);
if (p == 0) /* REQ_BUFSZ is too small! */
return STD_SYSERR;
t = trans(&hdr, buf, REQ_BUFSZ, &hdr, buf, REQ_BUFSZ);
if (ERR_STATUS(t))
return ERR_CONVERT(t);
if (ERR_STATUS(hdr.h_status))
return ERR_CONVERT(hdr.h_status);
p = buf_get_long(buf, buf + t, val1);
p = buf_get_long(p, buf + t, val2);
if (p == 0) /* server returned garbage */
return STD_SYSERR;
return STD_OK;
}

In general it is important that stub routines return an error status. This makes it much simpler for the client to deduce the cause of errors. Returning a null pointer or something similar on failure complicates things and a single errno-like variable is complicated and cumbersome in a multithreaded process.

Note once again the use of the buf_put and buf_get routines for marshaling data. There are routines for various data types. It is important that the server and the stub marshal the data in the same way or the results may be unfortunate.

#include "amoeba.h"
#include "stderr.h"
#include "stdlib.h"
#include "this_server.h"
#include "module/name.h"
main(argc, argv)
int argc;
char * argv[];
{
errstat err;
capability svr;
long num1, num2;
if (argc != 3) {
printf("Usage: %s num1 num2\n", argv[0]);
exit(1);
}
/* get the capability for the server */
if ((err = name_lookup(SERVER_CAP, &svr)) != STD_OK) {
printf("%s: lookup of %s failed: %s\n",
argv[0], SERVER_CAP, err_why(err));
exit(2);

}

- 9 -

num1 = strtol(argv[1], (char **) 0, 10);
num2 = strtol(argv[2], (char **) 0, 10);
/* send the command to the server */
if ((err = swap_longs(&svr, &num1, &num2)) != STD_OK) {
printf("%s: swap_longs failed: %s\n",
argv[0], err_why(err));
exit(3);
}
printf("new number order is %d %d\n", num1, num2);
exit(0);

}

Although it is possible to write the server loop and client stubs by hand it is also possible to generate the stubs and server loop using the Amoeba Interface Language (AIL). All the details of marshaling and unmarshaling data are handled by AIL. The precise details of how to use AIL are described in ail(U) and the chapter Programming Tools in this volume of the manual.

An important thing to watch out for is that AIL-generated servers or clients do not necessarily cooperate with hand-written servers or clients. The reason for this is that AIL may decide to marshal some of the parameters of an operation into the header. Another optimization it currently performs is the marshaling of parameters to and from request and reply buffers. Rather than marshaling the parameters in a byte- order independent way (using the buf_put routines, described earlier) it sends them over in the original byte-order. Additionally, one of the header fields is initialized to allow the server to see whether it is necessary to byte-swap parameters contained in the buffer.

In the next two sections we will reimplement the server described in the preceding sections. Only this time we will show how much of the labour required can be transferred to AIL.

In this section we will show how the example swap server can be implemented using AIL. The most important part of the AIL specification is the interface itself. An interface is defined by means of class definitions. For each command included in the class, the class definition specifies the prototype of the corresponding client stub. For example, the interface for the integer swap server could be specified as follows:

/* class file swap.cls */
#include "cmdreg.h"
#include "this_server.h"
class swaplong [DO_SWAP .. DO_NOTHING] {
do_swap [DO_SWAP] (*,
in out long first,
in out long second
);
do_nothing [DO_NOTHING] (*,
in out long first,
in out long second
);
};

It defines the class swaplong which consists of commands in the range from DO_SWAP up to DO_NOTHING. The client stub for the command DO_SWAP has three parameters: the ``*'', representing the capability for the object on which the operation is performed, and two long parameters

};

server;

/* Generate server main loop */

{

errstat err;
err = ml_swaplong(&get_cap.cap_port);
/* should never return */
printf("getreq failed: %s\n", err_why(err));
exit(1);

}

As soon as

a request has been accepted by ml_swaplong it will unmarshal the parameters of the

errstat
impl_do_swap(hdr, first, second)
header *hdr;
long *first, *second;
{
errstat check_cap();
long temp;

errstat err;

- 11 -

}

if ((err = check_cap(&hdr->h_priv, RGT_DOSWAP)) != STD_OK)
return err;
temp = *second;
*second = *first;
*first = temp;
return STD_OK;

Observe that, compared with function do_swap in the hand-coded example, the code is now almost trivial, because the programmer is not bothered with the marshaling of input and output data.
Combined with a completely analogous definition of impl_do_nothing and the functions main and check_cap taken from the original implementation, our AIL-based server is now complete.

Now we turn our attention to the client side. We have two options here. When a client program only consists of a command-line interface to a command supported by the server, AIL is able to generate the program all by itself. The other possibility is to let AIL only generate the client stubs, writing the rest of the program by hand. Although the latter option is a bit more work, it is also more flexible.
We will first show an AIL specification generating the entire client program do_swap:

#include "swap.cls"
generate swaplong {
client_interface;
client_stubs(do_swap);
command(do_swap);
};

The clause client_interface causes a header file swaplong.h containing C prototypes for the client stubs to be generated. The client stub for the operation DO_SWAP is requested by the client_stubs clause. It will be produced in the file do_swap.c. The rest of the program, which takes care of parsing the arguments, calling the stub and printing the results is requested by the command clause. It will be produced in the file cmd_do_swap.c.

It must be noted that the command produced is a direct reflection of the do_swap operation as defined in the class definition. More specifically, it requires the user to specify the name of the swap server capability as the first argument. The resulting program has the following interface:

$ swap /home/this_server/default 0 1
first=1
second=0

The other possibility is to use AIL only to generate the client stub do_swap. The AIL specification becomes:

#include "swap.cls"
generate swaplong {
client_interface;
client_stubs(do_swap);

#include "amoeba.h"

bufsize trans(request_hdr,
request_buf,
request_size,
reply_hdr,
reply_buf,
reply_size);

bufsize getreq(hdr, buf, size);

void putrep(hdr, buf, size);

interval timeout(length);

The three calls getreq, putrep, and trans form the remote procedure call (RPC) interface for interprocess communication. All point to point communication is, at the lowest accessible level, structured along the client/server model; that is, a client thread sends a request message to a service, one of the threads in one of the server processes gets the request, carries it out and returns a reply message to the client. There is also the possibility for group communication. This is described in grp(L). See also rawflip(L).

For historical reasons, a remote operation (a request followed by a reply) is called a message transaction or just a transaction. A client thread invokes a transaction by a call to trans. A server thread receives a request via a call to getreq and returns a reply by calling putrep. Trans, getreq, and putrep are blocking; that is, a trans suspends a thread until the request is sent, carried out and a reply is received; getreq suspends a thread until a request has been received and putrep suspends a thread until the reply has been received by the appropriate client thread's kernel.

A request or reply message is described to the transaction system calls by means of three parameters: a pointer to a header, a pointer to a buffer and the size of that buffer. The header is a fixed-length data structure, containing addressing information, status information, an operation code and some parameters. The buffer is an 8-bit-character array whose size may vary from 0 to 30000decimal

int8
} port;

_portbytes[PORTSIZE];

int8
uint8
port
} private;

prv_object[3];
prv_rights;
prv_random;

private cap_priv;
} capability;

port h_port;
port h_signature;

/* 6 bytes */ /* 6 bytes */

int32 h_offset;
bufsize h_size; /* 2 bytes */

/* 4 bytes */

uint16 h_extra;

/* 2 bytes */
/* total 32 bytes */

} header;

#define h_status h_command
/* alias: reply status */

The meaning of the fields is as follows:

h_port

This field is normally used in requests to hold an operation code which specifies which operation to carry out. In replies, it usually conveys the result of the operation back to the client (e.g., an error status). The field is not interpreted by the operating system.

h_offset

The name of this field was inspired by the use of transactions for reading and writing file objects. In the standard file read/write interface, it is used to specify offsets into a file. This 32-bit field may, however, be used as the application programmer sees fit. It is not interpreted by the operating system.

h_size

h_extra

These fields can be used to communicate arbitrary 16-bit quantities between client and server.
They are not interpreted by the operating system.

}

...

}

...

getreq

bufsize
getreq(hdr, buf, size)
header *hdr;
bufptr buf;
bufsize size;

header.h_port = server_get_port;
status = getreq(&header, buf, size);

putrep

void
putrep(hdr, buf, size)
header *hdr;
bufptr buf;
bufsize size;

trans

bufsize
trans(request_hdr, request_buf, request_size,
reply_hdr, reply_buf, reply_size)
header *request_hdr;
bufptr request_buf;

bufptr reply_buf;
bufsize reply_size;

timeout

interval
timeout(length)
interval length;

attempted operation.

Buffer length > 30000

The buffer length is an unsigned integer. It can not be less than zero. If it is larger than the
maximum size of a request or reply, an exception is raised and RPC_FAILURE is returned if the
exception is handled.

Getreq while serving, putrep while not serving

Programming errors, so an exception is raised. Putrep does not return a value, so when the
exception is caught no error code is returned.

Use of invalid pointers

Using pointers to headers or buffers wholly or partially in non-existent memory, to receive
headers or buffers in read-only memory, or to buffers straddling segment boundaries, an
exception is raised. If the exception is caught, trans and getreq additionally return
RPC_BADADDRESS.

Use of a NULL-port

When you forget to fill in the h_port field on getreq or trans, the system returns a
RPC_BADPORT failure. This is not an exception, because ports are often filled in with values
retrieved from remote sources such as the directory server. It seemed unreasonable to ask
application programmers to write code to check for NULL-ports when the system has to check
for them anyway.

Out of resources

This error can only occur under UNIXor UNIX-like systems. It is used when the Amoeba driver
could not get access to enough resources to send the message. It is guaranteed that the request
has not reached any server. If enough resources are freed the request can be safely repeated.

Two helpful macros are available for manipulating returned status codes: ERR_STATUS and ERR_CONVERT. They provide the proper casts from the 16-bit unsigned integers to signed integers for testing the sign bit. The macros are defined in amoeba.h.

The previous section specified that when a trans is blocked and a signal is received while the system is still trying to locate the server, trans will return the error code RPC_ABORTED. When the location of the server is known and the RPC has been sent to the server and no reply has been received as yet, the reaction of the system to signals to be caught is altogether different. In this case signals are propagated to the server. Thus the server will receive the signal and can choose to react accordingly. It can, as per default, ignore the signal or catch it. If the server ignores the signal the signal will have no effect in both server and client. If the server handles the signal it can choose its own way of reacting, for example by

- 21 -

returning an error reply with putrep. If the server itself catches signals and is waiting for a reply to a trans
the signal will again be propagated.

Signals can abort calls to getreq, but can not abort calls to putrep. See also signals(L).

The example below shows the typical server main loop for a very simple file server and a sample of client code for calling that server for a read operation and a write operation. Its is assumed that the client's capability has the put-port associated with the server's get-port.

#include "amoeba.h"
#include "cmdreg.h"
#include "stderr.h"

/* Server threads typically sit in an endless loop
* fielding and carrying out client requests
*/
for (;;) {
/* Put the server's get-port in the header.
* When the request
* arrives, it will be replaced by the put-port of the
* client's request.
*/

hdr.h_port = getport;
size = getreq(&hdr, buf, 100);
/* Check for errors. */
if (ERR_STATUS(size)) {
/* The macro ERR_CONVERT casts the 16-bit
* unsigned into an ordinary signed int.
*/
if (ERR_CONVERT(size) == RPC_ABORTED) {
/* When debugging a program, signals are used to
* checkpoint it. These abort getreq calls. When
* this happens, just try again.
*/
continue;
}
/* Other errors are bad */
fprintf(stderr, "Getreq error (%s)\n",
err_why(ERR_CONVERT(size)));
exit(-1);
}

/* Control gets here when a request is successfully
* received.
* Dispatch to the implementation routines for the
* different request types.
*/

switch (hdr.h_command) {

case F_READ:
/* Read implementation code goes here For the example,

}

- 22 -

* simulate the result of a successful read operation.
*/
size = hdr.h_size = 100;
hdr.h_status = STD_OK;
break;

case F_WRITE:
/* Same for write */
size = hdr.h_size = 0;
hdr.h_status = STD_OK;
break;

default:
/* Not a legal request type, return
* an error code
*/
hdr.h_status = STD_COMBAD;
}
/* Return a reply. No error codes are returned */
putrep(&hdr, buf, size);

#include "stderr.h"

/* Set transaction timeout to 30 seconds */
timeout(30000);

/* Fill in transaction header */
hdr.h_port = cap.cap_port; /* Server port */
hdr.h_priv = cap.cap_priv; /* Rest of file cap */
hdr.h_command = F_READ;
hdr.h_size = 100; /* Read 100 bytes .. */
hdr.h_offset = 0; /* .. from beginning of file

*/

/* Call the server; request buffer is empty,
* reply buffer is large enough to hold requested bytes
*/
size = trans(&hdr, NILBUF, 0, &hdr, buf, 100);

/* Size holds positive number of bytes read or
* negative error code.
*/
if (ERR_STATUS(size)) hdr.h_status = size;

/* Even if the transaction succeeds, the server may
* return an error code of its own. Convention is that
* the only success code is STD_OK (zero).
*/
if (hdr.h_status != STD_OK) {
/* Print an error message. The macro ERR_CONVERT
* casts the error code into an int. The function
* err_why converts standard error codes into a
* string.

*/

- 23 -

}

fprintf(stderr, "1st trans failed (%s)\n",
err_why(ERR_CONVERT(hdr.h_status)));
exit(-1);

/* The server returns number of bytes read in hdr.h_size.
* If the reply is truncated, or if the server is faulty
* the number of bytes received may not correspond to what
* the server claims was sent.
*/

if (size != hdr.h_size) {
/* In the case of file read, the client may be
* assumed not to ask for more than the buffer
* can hold, so this code is only reached if
* the server is faulty.
*/
fprintf(stderr, "message truncated\n");
exit(-1);

}

/* Read trans succeeded, try a write trans.
* Again, fill in header fields. Never trust what
* server left intact.
*/
hdr.h_port = cap.cap_port;
hdr.h_priv = cap.cap_priv;
hdr.h_command = F_WRITE;
hdr.h_size = 100;
hdr.h_offset = 0;

/* This time, request buffer is not empty */
size = trans(&hdr, buf, 100, &hdr, NILBUF, 0);

/* Size returned should be zero (empty reply buffer) */
if (ERR_CONVERT(size) != 0) hdr.h_status = size;
if (hdr.h_status != STD_OK) {
fprintf(stderr, "2nd trans failed (%s)\n",
err_why(ERR_CONVERT(hdr.h_status)));
exit(-1);
}

- 24 -

RPC server example

server_loop()
{
char *cp, *buf;
header h;
bufsize n, reply_size;
errstat err;
static capability mycap;
/* Is static just for initialization to 0 */
capability pubcap;
capability oldcap;
port check;
char pathbuf[257];
char *mycap_path;

buf=malloc(OMSIZE);
if(buf==0)
{
sys_log(SYS_FATAL,
"%s: server_loop: can't malloc buffer!\n",
progname);
my_exit(-1);
}

/* On startup, create a unique cap and store it.
*/
uniqport(&mycap.cap_port);
uniqport(&check);

priv2pub(&mycap.cap_port,&pubcap.cap_port);

if (prv_encode(&pubcap.cap_priv,
(objnum)0,
PRV_ALL_RIGHTS,
&check) < 0){

sys_log(SYS_FATAL,
"%s: can not prv_encode server cap\n",
progname);
my_exit(1);
}

/* check for old server cap ... */

if ((err = name_lookup(mycap_path, &oldcap))
== STD_OK)
{
err= name_replace(mycap_path,&pubcap);

if ( err != STD_OK && err != STD_NOTFOUND ) {
sys_log(SYS_FATAL,
"%s: name_replace %s failed (%s)\n",
progname, mycap_path, err_why(err));
my_exit(1);
}
/* Fall through on NOTFOUND & OK */
}

switch( err ) {

case STD_NOTFOUND:

- 25 -

if ((err = name_append(mycap_path,
&pubcap))
!= STD_OK) {
sys_log(SYS_FATAL,
"%s: name_append %s failed (%s)\n",
progname, mycap_path,
err_why(err));
my_exit(1);
}

case STD_OK:

default:
sys_log(SYS_FATAL,
"%s: name_lookup %s failed (%s)\n",
progname, mycap_path, err_why(err));
my_exit(1);
}

/* Server loop: */

for (;closing==0;) {

/* the get port */

h.h_port = mycap.cap_port;

reply_size = 0;

n = getreq(&h, buf, OMSIZE);

if (ERR_STATUS(n)) {
err = ERR_CONVERT(n);
if (err == RPC_ABORTED) {
continue;
}
sys_log(SYS_FATAL, "%s: getreq failed!\n");
my_exit(1);
}

switch (h.h_command) {

/* std_info request */

case STD_INFO:
(void) strcpy(buf, "object manager");
h.h_size = reply_size = strlen(buf);
h.h_status = STD_OK;
break;

/* std_status request */

case STD_STATUS:
cp = buf;
(void) strcpy(cp, "Object Manager:\n\n");
cp += strlen(cp);
sprintf(cp,"status=%s",om_server_status);

if ((reply_size = strlen(buf)) > OMSIZE)
reply_size = OMSIZE;

h.h_size = reply_size;
h.h_status = STD_OK;

break;

- 26 -

}

/* the server shutdown command */

case STD_EXIT:
{
rights_bits rights;
h.h_size=0;

/* the client needs full rights !!!*/

if(prv_decode(&h.h_priv,
&rights,
&check) ||
(rights != PRV_ALL_RIGHTS))
{
h.h_status=STD_DENIED;
}
else
{

closing=1;

h.h_status=STD_OK;
}
break;
}

/* unknown command */
default:
h.h_status = STD_COMBAD;
break;

#include "amoeba.h"
#include "module/ar.h"

char * ar_cap(cap_p)
char * ar_port(port_p)
char * ar_priv(priv_p)

char * ar_tocap(s, cap_p)
char * ar_toport(s, port_p) char * ar_topriv(s, priv_p)

To aid in debugging a set of routines has been provided to produce human-readable representations of capabilities and various subparts thereof.

The first three functions return a pointer to a string containing the ASCII representation of the bytes in a capability, port and private (see rpc(L)), respectively. Note that the string is in static data and subsequent calls by other threads or the same thread will overwrite the contents of the string. Each routine has its own static data so there are no interactions between the individual routines.

The latter three functions convert a string of the format returned by the first three routines to a capability, port and private, respectively. The ar_to functions assign to the capability, port or private, pointed to by the second parameter. They return a pointer to the character beyond the last character of the string. If the string is supposed to contain no extra characters, you should check that the returned pointer points to a NUL character.

If the string passed to an ar_to function is illegal, NULL is returned.
The format used is explained below.

Functions

ar_port

ar_port(port_p)
port *port_p;

ar_priv

char *
ar_priv(p)
private *p;

ar_cap

char *
ar_cap(cap_p)
capability *cap_p;

ar_tocap

char *
ar_tocap(s, cap_p)
char *s;

ar_toport

char *
ar_toport(s, port_p)
char *s;

ar_topriv

char *
ar_topriv(s, priv_p)
char *s;
private *priv_p;

- 29 -

The following code prints out an array of capabilities:

#include "amoeba.h"
#include "module/ar.n"
printcaps(caps, n)
capability caps[];
int n;
{
int i;

for (i = 0; i < n; ++i)
printf("Cap #%d: %s\n", i, ar_cap(&caps[i]));
}

The following function prints ``hello world'' and stores the port consisting of the bytes 1, 2, 3, 4, 5, 6 in p.

Hello()
{
port p;

printf("%s\n", ar_toport("1:2:3:4:5:6hello world", &p);

}

#include "amoeba.h"
#include "module/buffers.h"

char *buf_get_cap(p, endp, &val)
char *buf_get_capset(p, endp, &val)
char *buf_get_int16(p, endp, &val)
char *buf_get_int32(p, endp, &val)
char *buf_get_objnum(p, endp, &val)
char *buf_get_pd(p, endp, &val)
char *buf_get_port(p, endp, &val)
char *buf_get_priv(p, endp, &val)
char *buf_get_right_bits(p, endp, &val)
char *buf_get_string(p, endp, &val)
char *buf_put_cap(p, endp, &val)
char *buf_put_capset(p, endp, &val)
char *buf_put_int16(p, endp, val)
char *buf_put_int32(p, endp, val)
char *buf_put_objnum(p, endp, val)
char *buf_put_pd(p, endp, &val)
char *buf_put_port(p, endp, &val)
char *buf_put_priv(p, endp, &val)
char *buf_put_right_bits(p, endp, val)
char *buf_put_string(p, endp, val)

These functions get data from, or put data into, a character buffer in a format that is independent of any machine architecture; in particular of byte-order dependencies. They are primarily useful in loading and unloading RPC buffers (and reply buffers). All of them have the same calling sequence and return value, except for the type of the last argument.

In each case, p should point to the place within the buffer where data is to be stored or retrieved, and endp should point to the end of the buffer. (That is, the first byte after the buffer.)

For the buf_get functions, the val argument should be the address where the data retrieved from the buffer is to be stored. It must be a pointer to the type of value expected by the function. (See the individual function descriptions, below.)

buf_get_cap

char *
buf_get_cap(p, endp, valp)
char *p, *endp;

char *p, *endp;
capset *valp;

char *p, *endp;
int16 *valp;

buf_get_int32

char *
buf_get_int32(p, endp, valp)
char *p, *endp;

char *p, *endp;
objnum *valp;

buf_get_pd

char *
buf_get_pd(p, endp, valp)
char *p, *endp;

char *
buf_get_port(p, endp, valp)
char *p, *endp;
port *valp;

A port is retrieved from the buffer pointed to by p and copied to the port pointed to by valp.

buf_get_priv

char *p, *endp;
private *valp;

char *p, *endp;
rights_bits *valp;

buf_get_string

char *
buf_get_string(p, endp, valp)
char *p, *endp;

char *
buf_put_cap(p, endp, valp)
char *p, *endp;
capability *valp;

The capability pointed to by valp is copied into the buffer pointed to by p.

buf_put_capset

char *p, *endp;
capset *valp;

buf_put_int16

char *
buf_put_int16(p, endp, val)
char *p, *endp;

buf_put_int32

char *
buf_put_int32(p, endp, val)
char *p, *endp;

char
buf_put_objnum
char
objnum

Val, which

char *
buf_put_objnum(p, endp, val)
char *p, *endp;
objnum val;

should be an object number as found

in a capability, is stored in the buffer pointed to by p.

buf_put_pd

char *
buf_put_pd(p, endp, valp)
char *p, *endp;

buf_put_port

char *
buf_put_port(p, endp, valp)
char *p, *endp;

buf_put_priv

char *
buf_put_priv(p, endp, valp)
char *p, *endp;

buf_right_bits

char *
buf_put_right_bits(p, endp, val)
char *p, *endp;

char *
buf_put_string(p, endp, valp)
char *p, *endp;

char *valp;

- 36 -

The following code copies a capability, c, a 32-bit integer, i, a character string, s, into a transaction buffer,
then retrieves them into the variables c2, i2, and s2.

capability c, c2;
int32 i, i2;
char *s, *s2;
char buffer[1000];
char *p, *ep;

name_lookup(path, &c);
i = 17;
s = "foobar";

p = buffer;
ep = buffer + sizeof buffer;
p = buf_put_cap(p, ep, &c);
p = buf_put_int32(p, ep, i);
p = buf_put_string(p, ep, s);
if (!p) {
error("Buffer overflow during put");
}

p = buffer;
ep = buffer + sizeof buffer;
p = buf_get_cap(p, ep, &c2);
p = buf_get_int32(p, ep, &i2);
p = buf_get_string(p, ep, &s2);
if (!p) {
error("Buffer underflow during get");
}

#include "module/name.h"

errstat cwd_set(path)
errstat name_append(path, object)
char * name_breakpath(path, dir)
errstat name_create(path)
errstat name_delete(path)
errstat name_lookup(path, object)
errstat name_replace(path, object)

This module provides a portable, name-oriented interface to directory servers. It has the advantage of being independent of the particular directory server in use, but it does not make available all the functionality of every directory server, e.g., SOAP. It is similar to the module containing the same set of functions but with the prefix ``dir_'' instead of ``name_''. The main difference is that the ``dir_'' functions take an extra argument, origin, which is the capability for a directory relative to which the given path is to be interpreted.

In each function, the path should be a ``path name'' that specifies a directory or directory entry. To these functions, a directory is simply a finite mapping from character-string names to capabilities. Each (name, capability) pair in the mapping is a ``directory entry''. The capability can be for any object, including another directory; this allows arbitrary directory graphs (the graphs are not required to be trees). A capability can be entered in multiple directories or several times (under different names) in the same directory, resulting in multiple links to the same object. Note that some directory servers may have more complex notions of a directory, but all that is necessary in order to access them from this module is that they satisfy the above rules.

A path name is a string of printable characters. It consists of a sequence of 0 or more ``components'', separated by ``/'' characters. Each component is a string of printable characters not containing ``/''. As a special case, the path name may begin with a ``/'', in which case the first component starts with the next character of the path name. Examples: a/silly/path, /profile/group/cosmo-33.
If the path name begins with a ``/'', it is an ``absolute'' path name, otherwise it is a ``relative'' path name.

The interpretation of relative path names is relative to the current working directory. (Each Amoeba process has an independent capability for a current working directory, usually inherited from its creator -- see cwd_set below.)

(1)

If the path has no components (is a zero-length string), it specifies the directory d;

(2)

Otherwise, the first component in the path name specifies the name of an entry in directory d (either an existing name, or one that is to be added to the mapping);

(3)

If there are any subsequent components in the path name, the first component must map to the capability of a directory, in which case the rest of the components are recursively interpreted as a path name relative to that directory.

one of the capabilities encountered while parsing the path name did not have sufficient access
rights (for example, the directory in which the capability is to be installed is unwritable);

name_append

errstat
name_append(path, object)
char *path;

name_replace

errstat
name_replace(path, object)
char *path;

char *path;
capability *dir;

cwd_set

errstat
cwd_set(path)
char *path;

name_create(path)
char *path;

name_delete(path)
char *path;

Name_delete deletes the entry path from the directory server. The object specified by the capability associated with path in the directory entry is not destroyed. If desired, it should be separately destroyed (see std_destroy(L)).

Required Rights:
SP_MODRGT in the directory that is to be modified

name_lookup

errstat
name_lookup(path, object)
char *path;
capability *object;

Name_lookup finds the capability named by path and stores it in object.

/* Change the name /home/abc to /home/xyz: */
capability mod_dircap, object;
char *old_name = "/home/abc";
char modify_dir[NAME_MAX+1];
char *entry_name = name_breakpath(old_name, &mod_dircap);

if (entry_name != NULL) {
strncpy(modify_dir, old_name, entry_name - old_name);
modify_dir[entry_name - old_name] = '\0';
if (cwd_set(modify_dir) == STD_OK &&
name_lookup(entry_name, &object)== STD_OK &&
name_append("xyz", &object) == STD_OK &&
name_delete(entry_name) == STD_OK) {
fprintf(stderr, "Successful name change\n");
return;
}
fprintf(stderr, "Error -- no name change\n");
}

#include "amoeba.h"

void
priv2pub(priv, pub)
port *priv; /* in */
port *pub; /* out */

The Amoeba publications describe how a one-way function is applied by the F-box to convert a get-port to a put-port. This routine is used to implement the F-box in software. The priv2pub function is a one-way function (in that it is extremely difficult to invert) which is used to encrypt the port of a server.

Priv2pub converts a private port (also known as a get-port) to a public port (also known as put-port). A private port is the port used by a server in its getreq call; a public port is the port used by a client of that server in its trans call (see rpc(L)). When getreq is called the kernel calls priv2pub to encrypt the private port and only accepts requests to the encrypted port. Thus it is difficult for someone to pretend to be a server for which they do not know the get-port. Note that when getreq returns the header argument will contain the put-port since that is what the client sent.

It is legal for the priv and pub arguments to point to the same location. Neither should be a NULL-pointer.

#include "amoeba.h"
#include "module/prv.h"

int prv_decode(prv, prights, random)
int prv_encode(prv, obj, rights, random)
objnum prv_number(prv)

These functions are used by servers to make and validate capabilities and to extract the object number from a capability.

Functions

prv_decode

int
prv_decode(prv, prights, random)
private *prv;
rights_bits *prights;
port *random;

Prv_decode is used to validate a capability when the original random number is known. It operates on the private part of the capability. It checks the check field in prv and if the check field is valid it returns in prights the rights in the capability. It returns 0 if it succeeded and -1 if the check field was invalid. If prv_decode fails then the capability was not valid and should be rejected.

prv_encode

int
prv_encode(prv, obj, rights, random)
private *prv;
objnum obj;
rights_bits rights;

port *random;

- 44 -

Prv_encode builds a private part of a capability in prv using the object number obj, the rights field rights and the check field pointed to by random. It returns 0 if it succeeded and -1 if the rights or the obj argument exceeded the implementation limits.

prv_number

objnum
prv_number(prv)
private *prv;

Prv_number returns the object number from the private part prv.

Warnings

The current implementation restricts the object number to 24 bits and the rights field to 8 bits.

The following function implements the std_restrict operation:

errstat
impl_std_restrict(cap, mask, newcap)
capability *cap;
rights_bits mask;
capability *newcap;
{
objnum obj;
rights_bits rights;
struct foobar {
port random; /* Random checkword */
...
}

*foo, *FindFoo();

/* Find object: */

obj = prv_number(&cap->cap_priv);

if ((foo = FindFoo(obj)) == NULL)
return STD_CAPBAD; /* Never heard of */
/* Validate: */

if (prv_decode(&cap->cap_priv, &rights, &foo->random) != 0)
return STD_CAPBAD; /* Do not trust cap */

/* Build new cap: */
rights &= mask;
newcap->cap_port = cap->cap_port;

- 45 -

if (prv_encode(&newcap->cap_priv, obj, rights, &foo->random) != 0)
return STD_SYSERR; /* Should not happen */
return STD_OK;

}

- 46 -

std_params programming interface

std_params - standard client-server interface for setting or controlling server run
parameters in a human friendly way

time

#include <stdcmd.h>

errstat std_getparams(capability server*,
char *parambuf,
int bufsize,
int *paramlen,
int *nparams);
errstat std_setparams(capability server*,
char parambuf*,
int paramlen,
int nparams);

The std_params interface provides an easy way to get or set server parameters. You can use
the std_params[A] util to show or change settings.

Client interface

std_getparams

errstat
std_getparams(capability *server,
char *parambuf,
int bufsize,
int *paramlen,
int nparams);

This client request function returns in parambuf (of size bufsize) the parameter list supported by
the server with server capability server.
Buffer format:

for each parameter:
name\0
type\0
description\0
current value\0

std_setparams

errstat

- 47 -

std_setparams(capability *server,
char *parambuf,
int paramlen,
int nparams);

This function set one or more server parameters nparams. The parameter list is stored in the
buffer parambuf of length paramlen.
Buffer format:

for each parameter:
name\0
new value\0

To store or retrieve the parameters from the buffer, use the buf_put_string and buf_get_string
functions ( buffer[L] ).

All values, independent of their meaning (long, char, string...) are always stored as strings!

Server interface

For the server side, no library functions exist. It's the work of the programmer to implement the
std_params interface in the server service loop.

You must add the STD_GETPARAMS and STD_SETPARAMS commands in your service loop
and extract the following parameters:

hdr.h_command = STD_GETPARAMS
hdr.h_extra = maximal size of parambuf on
the client side
buffer

-> put the parameters in the right order with
buf_put_string

return:
hdr.h_extra = paramlen (size of parambuf)
hdr.h_size = nparams (total number of parameters)

hdr.h_command = STD_SETPARAMS
hdr.h_extra = paramlen
hdr.h_size = nparams

buffer

-> get the parameters from the buffer with
buf_get_string

Client side

Setting only one parameter each time shows the next example. The server capability was
retrieved with the name_lookup function for example ( name[L] ):

errstat
do_std_setparam(cap, param, value)

capability *cap;
char *param;
char *value;
{
errstat err;
size_t length;
char *buf;
char *bufp, *end;

- 48 -

}

length = strlen(param) + strlen(value) + 2;
buf = (char *)malloc(length);
if (buf == NULL) {
return STD_NOSPACE;
}

bufp = buf;
end = &buf[length];

bufp = buf_put_string(bufp, end, param);
bufp = buf_put_string(bufp, end, value);

if (bufp == NULL) {
err = STD_NOSPACE;
} else {
err = std_setparams(cap, buf, (int)length, 1);
}
free(buf);

return err;

struct param {
char *par_name;
char *par_type;
char *par_descr;
char *par_value;
};

errstat
do_get_params(cap, ret_params, ret_nparams)
capability *cap;
struct param **ret_params;
int *ret_nparams;
{
errstat err;
int i, paramlen, numparams;
struct param *params;
char *parambuf;
char *bufp, *end;

parambuf = (char *)malloc((size_t)MAX_PARAM_LEN);
if (parambuf == NULL) {
return STD_NOSPACE;
}

err = std_getparams(cap,
parambuf, MAX_PARAM_LEN,
&paramlen, &numparams);
if (err != STD_OK) {
return err;

}

- 49 -

params = (struct param *)
malloc((size_t)(numparams *
sizeof(struct param)));
if (params == NULL) {
free(parambuf);
return STD_NOSPACE;
}

bufp = parambuf;
end = &parambuf[paramlen];

for (i = 0; i < numparams && bufp != NULL; i++) {
char *s;

bufp = fetch_string(bufp, end,
&params[i].par_name);
bufp = fetch_string(bufp, end,
&params[i].par_type);
bufp = fetch_string(bufp, end,
&params[i].par_descr);
bufp = fetch_string(bufp, end,
&params[i].par_value);
}

free(parambuf);

if (i < numparams) {
free(params);
/* also freeing the strings here isn't worth
* the trouble
*/
return STD_NOSPACE;
}

*ret_params = params;
*ret_nparams = numparams;
return STD_OK;

}

/*

* Get server parameters (name, type, description,
* value).
*/

static char *
fetch_string(buf, end, str)
char *buf, *end;
char **str;
{
char *bufp, *s;

bufp = buf_get_string(buf, end, &s);
if (bufp != NULL) {
*str = (char *)malloc((size_t)(strlen(s) + 1));
if (*str == NULL) {
fprintf(stderr, "could not allocate
string\n");
exit(1);
}
(void)strcpy(*str, s);
}
return bufp;
}

{

...

n = getreq(&h, buf, OMSIZE);
if (ERR_STATUS(n)) {
err = ERR_CONVERT(n);
if (err == RPC_ABORTED) {
continue;
}
sys_log(SYS_FATAL,
"%s: getreq failed!\n");
my_exit(1);
}
switch (h.h_command) {

...

case STD_GETPARAMS:
{
int N; /* in redeclared (h_extra) */
int paramlen; /* out redeclared (h_extra) */
int nparams; /* out redeclared (h_size) */
/* out parambuf not declared */
if (n != 0) {
h.h_status = STD_ARGBAD;
break;
}
N = (short) h.h_extra;
h.h_status = om_std_getparams(&h,
buf,
/* bound: */ OMSIZE,
N,
&paramlen,
&nparams);
if (h.h_status == 0) {
h.h_extra =
(unsigned short int )paramlen;
h.h_size =
(unsigned short int )nparams;
reply_size=paramlen;
/* for parambuf */
}
else
reply_size=0;

break;
}

case STD_SETPARAMS:
{
int paramlen;/* in redeclared (h_extra) */
int nparams;/* in redeclared (h_size) */
/* in parambuf not declared */
paramlen = (short) h.h_extra;
nparams = (short) h.h_size;
h.h_status = om_std_setparams(&h,
buf,
/* bound: */ OMSIZE,
paramlen,
nparams);
reply_size=0;
break;

}

}

default:
h.h_status = STD_COMBAD;
break;

}

putrep(&h, buf, reply_size);

/*
* std_getparams implementation
*/

static char *
put_long_var(buf, end, name, min, max, type, descr, value)
char *buf, *end; /* buffer start and end */
char *name; /* name of the variable */
long min, max; /* minimum and maximum value (to
create type string) */
char *type; /* the "currency" of the type */
char *descr; /* a short description telling what
the param does */
long value; /* the current value */

/*
* Put the string representation of an integer variable
* in a buffer,
* in the format required by std_getparams().
*/

{
register char *bufp = buf;

/* name\0 */
bufp = buf_put_string(bufp, end, name);

/* type\0 */
if ((bufp != NULL) && (end - bufp >= 20 +
strlen(type))) {
/* type is actually a subrange: */
sprintf(bufp, "%ld..%ld %s", min, max, type);

/* skip value until after nul byte */
bufp = strchr(bufp, '\0');
bufp++;
}

/* description\0 */
bufp = buf_put_string(bufp, end, descr);

/* value\0 */
if ((bufp != NULL) && (end - bufp >= 10)) {
sprintf(bufp, "%ld", value);

/* skip value until after nul byte */
bufp = strchr(bufp, '\0');
bufp++;
}

return bufp;
}

header *h;
char *buf;

/* to put params in */

int max_buf;
int n;

/* length of client buffer */

int *len;
int *nparams;
{

int

/* length of buffer returned */
/* number of parameters returned */

np;

char
errstat

*bufp, *end;
err;

}

if (n < 0) {
return STD_ARGBAD;
}
if (n > max_buf) {
n = max_buf;
}
bufp = buf;
end = &buf[n];

np = 0;
bufp = put_long_var(bufp, end, NAME_OMSLOWDOWN,
0,1, "0/1",
INFO_OMSLOWDOWN,
om_slowdown);
np++;
bufp = put_long_var(bufp, end, NAME_OMWAIT,
0,1, "0/1",
INFO_OMWAIT,
om_wait);
np++;
bufp = put_long_var(bufp, end, NAME_OMSLEEP,
MIN_OMSLEEP, MAX_OMSLEEP, "sec",
INFO_OMSLEEP,
delay_between_start_of_passes);
np++;

if (bufp == NULL) {
return STD_OVERFLOW;
}

*nparams = np;
*len = bufp - buf;
return STD_OK;

/*
* std_setparams implementation
*/

static errstat
set_long_var(var, strvalue, min, max)
long *var;
char *strvalue;
long min, max;

{

- 53 -

char *after_val;
long value;

}

/* first convert string to integer */
value = strtol(strvalue, &after_val, 0);
if (after_val == strvalue) {
/* could not get integer out of strvalue */
return STD_ARGBAD;
}

/* perform range check */
if (value < min || value > max) {
return STD_ARGBAD;
}

*var = value;
return STD_OK;

errstat
om_set_param(param, val)
char *param;
char *val;
{
errstat err = STD_NOTFOUND;
/* unknown parameter name */

if (strcmp(param, NAME_OMSLOWDOWN) == 0) {

err = set_long_var(&om_slowdown, val,0,1);

} else if (strcmp(param, NAME_OMSLEEP) == 0) {

err = set_long_var(&delay_between_start_of_passes,
val,MIN_OMSLEEP, MAX_OMSLEEP);

if(err == STD_OK)
omsleepchange=1;
} else if (strcmp(param, NAME_OMWAIT) == 0) {
int iarg;

err = set_long_var(&iarg,val,0,1);
if(err == STD_OK && om_wait == 0 && iarg == 1)
{
om_wait = 1;
sema_down(&om_semawait);
}
if(err == STD_OK && om_wait == 1 && iarg == 0)
{
om_wait = 0;
sema_up(&om_semawait);
}
} else
err=STD_ARGBAD;

if (err != STD_OK) {
sys_log(SYS_ERROR,
"%s: refused to set parameter \"%s\" (%s)\n",
progname,param, err_why(err));
}

return err;

}

- 54 -

void uniqport(p)
void uniqport_reinit()

Routines to generate unique RPC and group communication ports and check fields.

uniqport

void
uniqport(p)
port * p;

Uniqport produces a non-NULL, random port. In general the result should be unique to the system. It is useful for servers that need to create new check fields or a new port to listen to. It uses a random number server to get the seed for the random number generator.

uniqport_reinit

void
uniqport_reinit()

Uniqport_reinit causes the next call to uniqport to choose a new seed for the generation of random numbers.

Environment Variables

- 56 -

If set, RANDOM determines which random number server to use when generating the seed. Otherwise the default random server is used.

Warnings

It is possible that the port generated is not unique within the system. If it is to be used as a port then it may be necessary to test to see if anyone is already listening to that port before using it. This is done by doing a std_info (see std(L)) on the port with a short locate timeout (say 2 seconds).

#include "amoeba.h"
#include "module/rnd.h"

port listen;

uniqport(&listen);

Table of Contents

Client/Server Tutorial .................................................................................................................

2

Writing Servers and Clients.....................................................................................................
Servers................................................................................................................................. Clients .................................................................................................................................. Using AIL............................................................................................................................. Writing a Server with AIL ......................................................................................................

2
2
7
9
9