Unison/NANO: dir

NAME

dir_register, dir_deregister, dir_lookup, dir_lookup_string - directory service routines

SYNOPSIS

#include <sys.h>

int dir_register( char *name , uint value, uint type );
int dir_deregister( char *name );
int dir_lookup( char *name , uint *valuep );
int dir_lookup_string( char *name , uint *valuep , size_t len );
int dir_lookup_type( dir_buf_type_t *Dir_buf_ptr , uint type );
typedef struct dir_buf_entry_type {: struct dir_buf_entry_type *next_entry_ptr; //pointer to next entry; uint value; //value; char *name; //pointer to name; }dir_buf_type_t;

DESCRIPTION

These routines provide an interface to the directory service. The directory service provides a generic way of associating a name with a value. The registered value may also have a given type. A common use is to associate a pthread id with a name so that other threads can rendezvous with the thread.

A name can be associated with a value with a call to dir_register(). The value associated with name may then be retrieved with a call to dir_lookup() or dir_lookup_string(). The entry for name may be removed with a call to dir_deregister().

Several names may share the same value; however, each name must be unique.

The type is used to allow users to look up values by class. By associating a type with a name and a value, all instances of a given type may be retreived. This feature is used to retreive all servers for example. The structure for the single linked list is shown above.

dir_lookup_type() is used to lookup all names and values associated with a given type. This is very useful to lookup all system objects of a given type. The various pre-defined system types are defined in sys.h as follows.

#define TYPE_UNKNOWN 0
#define TYPE_THREAD 1
#define TYPE_SERVER 2
#define TYPE_SEMAPHORE 3
#define TYPE_MUTEX 4
#define TYPE_MQUEUE 5
#define TYPE_BARRIER 6
#define TYPE_TIMER 7
#define TYPE_POOL 8
#define TYPE_ENV 9
#define TYPE_COND_VAR 10

RETURN VALUES

The calls return a 1 if successful, and 0 on error except for dir_lookup_type(). dir_lookup_type() returns a count of the number of entries found or -1 with errno set if there is an error.

ERRORS

If dir_register() fails, it returns 0 and sets errno. dir_lookup_type() is the only function to return -1 on error and it sets errno using the same error codes.

EEXIST: A value has already been registered to the specified name.
ENOSPC: Unable to allocate memory for the new entry.

For multiprocessor systems only, all calls can return:

EBADID: Unable to access the Directory thread.

NOTES

In a multiprocessor system, the service is provided by the Directory thread.