Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CUSE4BSD(3)		 BSD Library Functions Manual		   CUSE4BSD(3)

NAME
     libcuse4bsd -- Userland character device library

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"

     #include <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	suc-
     cess or a negative	CUSE_ERR_XXX value on failure.	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
     CUSE_ERR_XXX value	on failure.

UNIT MANAGEMENT
     int cuse_alloc_unit_number(int *) This function stores a unique system
     unit number at the	pointed	integer	loation. This function returns 0 on
     success or	a negative CUSE_ERR_XXX	value on failure.

     int cuse_free_unit_number(int) This function frees	the given allocated
     system unit number. This function returns 0 on success or a negative
     CUSE_ERR_XXX value	on failure.

LIBRARY	USAGE
     void * cuse_vmalloc(int size) This	function allocates size	bytes of mem-
     ory. 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.

     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	unique 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 pa-
     rameters. 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	previ-
     ously 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 nega-
     tive CUSE_ERR_XXX value on	failure.

     void cuse_dev_set_per_file_handle(struct cuse_dev *, void *) , void *
     cuse_dev_get_per_file_handle(struct cuse_dev *) 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	appli-
     cation.

     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 ap-
     plication.	These functions	must be	used when operating on the data	point-
     ers passed	to the cm_read(), cm_write() and cm_ioctl() callback func-
     tions. These functions returns 0 on success or a negative CUSE_ERR_XXX
     value on failure.

     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 CUSE_ERR_XXX value.

     struct cuse_dev * cuse_dev_get_current(int	*pcmd) This function is	used
     to	get the	current	cuse device pointer and	the currently executing	com-
     mand, by CUSE_CMD_XXX value. The pcmd argument is allowed to be NULL.
     This function should only be used inside the cuse file operation call-
     backs. 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	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 ac-
     tually 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	fail-
     ure 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 .

BSD			       February	11, 2010			   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | LIBRARY INITIALISATION / DEINITIALISATION | UNIT MANAGEMENT | LIBRARY USAGE | LIBRARY CALLBACK METHODS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cuse4bsd&sektion=3&manpath=FreeBSD+9.0-RELEASE+and+Ports>

home | help