resmgr(3)

NAME
resmgr - resource manager library functions

SYNOPSIS
#include <resmgr.h>

char **rsm_list_devices(const char *family);
int rsm_open_device(const char *pathname, int flags);
int rsm_open_socket(const char *pathname);
int rsm_open_device_as(const char *family, const char *pathname,
                        int flags);
int rsm_login(const char *user, const char *id);
int rsm_logout(const char *user);
int rsm_grant(const char *user, const char *classname);
int rsm_add_device(const char *device, const char *classname);
int rsm_remove_device(const char *device, const char *classname);
int rsm_lock_device(const char *device);
int rsm_unlock_device(const char *device);
char **rsm_list_sessions(void);
int rsm_command(int *codeptr, const char *fmt, ...);

DESCRIPTION
This manual page lists the resource manager functions available to client applications. All functions connect to the resource manager daemon resmgrd(8), transmit one or more commands, and close the connection.

  User functions
The following functions are intended to be used by user applications wishing to open or lock a device.

char **rsm_list_devices(const char *family)
    This function will return the list of devices the client is permitted to open.

    The optional family argument can be used to specify a resource family. If specified, the listing will include only names from that specific family. In addition, device names will be mapped to that particular name space.

    For instance, if the resource class includes the device /dev/cdrom, listing the scsi family would return a corresponding SCSI device specifier such as scsi:0,0,1. (Of course, this assumes that /dev/cdrom uses the SCSI CD driver, and that the user has permission to open the corresponding raw SCSI device).

int rsm_open_device(const char *pathname, int flags)
    This function will open the device specified by pathname.

    The flags argument contains the usual flags recognized by open(2), including O_RDWR, O_RDONLY, and O_NONBLOCK. O_WRONLY is not supported; the resource manager will silently use O_RDWR instead.

int rsm_open_socket(const char *pathname")
    This function will open a local socket and connect to the named path.

int rsm_open_device_as(const char *family,
    const char *pathname, int flags)
    This function will open a device from the specified family, related to the the device specified by pathname. For instance, if you specify a family of scsi, and a device of /dev/cdrom, this will as the resource manager to open the raw SCSI device associated with the CDROM (if there is any, and if /dev/cdrom has the scsi flag set (see resmgr.conf(5)).

    If there is no corresponding device in the indicated family, access is denied.

    The flags argument has the same meaning as with rsm_open_device.

    Instead of the path name of a device, you can also identify the SCSI device using its SCSI ID, using the notation [bus,]target,lun.

int rsm_lock_device(const char *device)
    This function will create a lock file for device. If a conflicting lock exists, an error is returned.

int rsm_unlock_device(const char *device)
    This will remove a previously created lock file. The lock file must have been created by the calling user, or the lock file must be stale (i.e. the PID listed in the file does not correspond to a currently running process).

  Administrative Functions
The following functions are administrative and are restricted to the administrator:

int rsm_login(const char *user, const char *id)
    This function will establish a resource manager session for user . The id argument is a identifier uniquely describing where the user is logged in. For instance, if the user is logged in at the console or via remote login, id would usually specify the tty on which the user is logged in. Graphic logins such as kdm or gdm would probably use the X11 display string.

int rsm_logout(const char *id)
    This function destroys the resource manager session for the given identifier. If this was the last session for the user, the user's access rights to devices managed by resmgrd are revoked.

int rsm_grant(const char *user, const char *classname)
    This function grants user access to resource class classname.

int rsm_revoke(const char *user, const char *classname)
    This function revokes user's access rights to class classname. If classname is NULL, all access rights of the user are revoked.

int rsm_add_device(const char *device, const char *classname)
    Add device device to class classname. The device will immediately become accessible to all users who have been granted access to this class.

int rsm_remove_device(const char *device,
    const char *classname)
    Remove the specified device from class classname.

char **rsm_list_sessions(void)
    This function returns the list of all currently active sessions.

int rsm_command(int *codeptr, const char *fmt, ...)
    This function lets you send verbatim commands to the resmgr daemon. This allows you to work around limitations of the C API described above. fmt is a printf-like format string, optionally followed by arguments, such as

    rsm_command(NULL, add %s desktop scsi , devname)

    codeptr is a pointer to an integer. In the case of an error flagged by the server, rsm_command will set this to the response code returned by the server. If you're not interested in the server response code, pass NULL for codeptr.

RETURN VALUE
rsm_open_device and rsm_open_device_as return a file descriptor for the opened device on success, and -1 on error.

rsm_list_devices and rsm_list_sessions return a pointer to a string array, terminated by a NULL pointer. If the list is empty, and empty array is returned. A return value of NULL indicates an error.

It is the caller's responsibility to free the array and the string pointers it contains.

All other functions return 0 in case of success, and -1 otherwise.

AUTHOR
Olaf Kirch <okir@lst.de>

SEE ALSO
resmgrd(8), resmgr(1).