GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CUSE4BSD (3)

NAME

libcuse4bsd - Userland character device library

CONTENTS

Library
Synopsis
Description
Library Initialisation / Deinitialisation
Unit Management
Library Usage
Library Limitations
Library Callback Methods
See Also
History

LIBRARY

Userland character device library (libcuse4bsd -lcuse4bsd)

SYNOPSIS

To load the required kernel module at boot time, place the following line in loader.conf(5):

cuse4bsd_load="YES"


.In cuse4bsd.h

DESCRIPTION

The libcuse4bsd library contains functions to create a character device in userspace. The libcuse4bsd library is thread safe.

LIBRARY INITIALISATION / DEINITIALISATION

int cuse_init void This function initialises libcuse4bsd. Must be called at the beginning of the program. This function returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes. If the cuse4bsd kernel module is not loaded, CUSE_ERR_NOT_LOADED is returned.

int cuse_uninit void Deinitialise libcuse4bsd. Can be called at the end of the application. This function returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.

UNIT MANAGEMENT

int cuse_alloc_unit_number int * This function stores a uniq system unit number at the pointed integer loation. This function returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.

int cuse_alloc_unit_number_by_id int * int id This function stores a uniq system unit number at the pointed integer loation. The returned unit number is uniq within the given ID. Valid ID values are defined by the cuse4bsd include file. See the CUSE_ID_XXX() macros for more information. This function returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.

int cuse_free_unit_number int This function frees the given allocated system unit number. This function returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.

int cuse_free_unit_number_by_id int unit int id This function frees the given allocated system unit number belonging to the given ID. If both the unit and id argument is -1, all allocated units will be freed. This function returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.

LIBRARY USAGE

void * cuse_vmalloc int size This function allocates size bytes of memory. Only memory allocated by this function can be memory mapped by mmap(). This function returns a valid data pointer on success or NULL on failure.

int cuse_is_vmalloc_addr void * This function returns non-zero if the passed pointer points to a valid and non-freed allocation, as returned by "cuse_vmalloc()". Else this function returns zero.

void cuse_vmfree void * This function frees memory allocated by cuse_vmalloc(). Note that the cuse4bsd library will internally not free the memory until the cuse_uninit() function is called and that the number of uniq allocations is limited.

unsigned long cuse_vmoffset void * This function returns the mmap offset that the client must use to access the allocated memory.

struct cuse_dev * cuse_dev_create const struct cuse_methods *mtod void *priv0 void *priv1 uid_t gid_t int permission const char *fmt ... This function creates a new character device according to the given parameters. This function returns a valid cuse_dev structure pointer on success or NULL on failure. The device name can only contain a-z, A-Z, 0-9, dot, / and underscore characters.

void cuse_dev_destroy struct cuse_dev * This functions destroys a previously created character device.

void * cuse_dev_get_priv0 struct cuse_dev * , void * cuse_dev_get_priv1 struct cuse_dev * , void cuse_dev_set_priv0 struct cuse_dev * void * , void cuse_dev_set_priv1 struct cuse_dev * void * These functions are used to set and get the private data of the given cuse device.

int cuse_wait_and_process void This function will block and do event processing. If parallell I/O is required multiple threads must be created looping on this function. This function returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.

void * cuse_dev_get_per_file_handle struct cuse_dev * , void cuse_dev_set_per_file_handle struct cuse_dev * void * These functions are used to set and get the per-file-open specific handle and should only be used inside the cuse file operation callbacks.

void cuse_set_local int This function instructs cuse_copy_out() and cuse_copy_in() that the user pointer is local, if the argument passed to it is non-zero. Else the user pointer is assumed to be at the peer application. This function should only be used inside the cuse file operation callbacks. The value is reset to zero when the given file operation returns, and does not affect any other file operation callbacks.

int cuse_copy_out const void *src void *peer_dst int len , int cuse_copy_in const void *peer_src void *dst int len These functions are used to transfer data between the local application and the peer application. These functions must be used when operating on the data pointers passed to the cm_read(), cm_write() and cm_ioctl() callback functions. These functions return 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.

int cuse_got_peer_signal void This function is used to check if a signal has been delivered to the peer application and should only be used inside the cuse file operation callbacks. This function returns 0 if a signal has been delivered to the caller. Else it returns a negative value. See CUSE_ERR_XXX for known error codes.

struct cuse_dev * cuse_dev_get_current int *pcmd This function is used to get the current cuse device pointer and the currently executing command, by CUSE_CMD_XXX value. The pcmd argument is allowed to be NULL. This function should only be used inside the cuse file operation callbacks. On success a valid cuse device pointer is returned. On failure NULL is returned.

void cuse_poll_wakeup void This function will wake up any file pollers.

LIBRARY LIMITATIONS

Transfer lengths for read, write, cuse_copy_in and cuse_copy_out should not exceed what can fit into a 32-bit signed integer and is defined by the CUSE_LENGTH_MAX macro. Transfer lengths for ioctls should not exceed what is defined by the CUSE_BUFFER_MAX macro.

LIBRARY CALLBACK METHODS

In general fflags are defined by CUSE_FFLAG_XXX and errors are defined by CUSE_ERR_XXX.
enum {
  CUSE_ERR_NONE
  CUSE_ERR_BUSY
  CUSE_ERR_WOULDBLOCK
  CUSE_ERR_INVALID
  CUSE_ERR_NO_MEMORY
  CUSE_ERR_FAULT
  CUSE_ERR_SIGNAL
  CUSE_ERR_OTHER
  CUSE_ERR_NOT_LOADED

CUSE_POLL_NONE CUSE_POLL_READ CUSE_POLL_WRITE CUSE_POLL_ERROR

CUSE_FFLAG_NONE CUSE_FFLAG_READ CUSE_FFLAG_WRITE CUSE_FFLAG_NONBLOCK

CUSE_CMD_NONE CUSE_CMD_OPEN CUSE_CMD_CLOSE CUSE_CMD_READ CUSE_CMD_WRITE CUSE_CMD_IOCTL CUSE_CMD_POLL CUSE_CMD_SIGNAL CUSE_CMD_SYNC CUSE_CMD_MAX };

int cuse_open_t struct cuse_dev * int fflags This functions returns a CUSE_ERR_XXX value.

int cuse_close_t struct cuse_dev * int fflags This functions returns a CUSE_ERR_XXX value.

int cuse_read_t struct cuse_dev * int fflags void *peer_ptr int len This functions returns a CUSE_ERR_XXX value in case of failure or the actually transferred length in case of success. cuse_copy_in() and cuse_copy_out() must be used to transfer data to and from the peer_ptr.

int cuse_write_t struct cuse_dev * int fflags const void *peer_ptr int len This functions returns a CUSE_ERR_XXX value in case of failure or the actually transferred length in case of success. cuse_copy_in() and cuse_copy_out() must be used to transfer data to and from the peer_ptr.

int cuse_ioctl_t struct cuse_dev * int fflags unsigned long cmd void *peer_data This functions returns a CUSE_ERR_XXX value in case of failure or zero in case of success. cuse_copy_in() and cuse_copy_out() must be used to transfer data to and from the peer_data.

int cuse_poll_t struct cuse_dev * int fflags int events This functions returns a mask of CUSE_POLL_XXX values in case of failure and success. The events argument is also a mask of CUSE_POLL_XXX values.

struct cuse_methods {
  cuse_open_t *cm_open;
  cuse_close_t *cm_close;
  cuse_read_t *cm_read;
  cuse_write_t *cm_write;
  cuse_ioctl_t *cm_ioctl;
  cuse_poll_t *cm_poll;
};

SEE ALSO

HISTORY

libcuse4bsd was written by Hans Petter Selasky .
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.