File: cuse4bsd.3

package info (click to toggle)
cuse4bsd 0~svn2434-2
  • links: PTS
  • area: main
  • in suites: jessie-kfreebsd
  • size: 140 kB
  • sloc: ansic: 2,017; makefile: 42
file content (360 lines) | stat: -rw-r--r-- 9,704 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
.\"
.\" Copyright (c) 2010-2012 Hans Petter Selasky
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd May 27, 2012
.Dt CUSE4BSD 3
.Os
.Sh NAME
.Nm libcuse4bsd
.
.Nd "Userland character device library"
.
.
.Sh LIBRARY
.
.
Userland character device library (libcuse4bsd -lcuse4bsd)
.
.
.Sh SYNOPSIS
.
.Pp
To load the required kernel module at boot time, place the following line in
.Xr loader.conf 5 :
.Bd -literal -offset indent
cuse4bsd_load="YES"
.Ed
.
.Pp
.
.In cuse4bsd.h
.
.
.Sh DESCRIPTION
The
.Nm
library contains functions to create a character device in userspace. The
.Nm
library is thread safe.
.
.
.Sh LIBRARY INITIALISATION / DEINITIALISATION
.
.Pp
.
.Ft "int"
.Fn "cuse_init" "void"
This function initialises
.Nm .
Must be called at the beginning
of the program. This function returns 0 on success or a negative
CUSE_ERR_XXX value on failure.
If the cuse4bsd kernel module is not loaded, CUSE_ERR_NOT_LOADED is
returned.
. 
.Pp
.
.Ft "int"
.Fn "cuse_uninit" "void"
Deinitialise
.Nm .
Can be called at the end of the
application. This function returns 0 on success or a negative
CUSE_ERR_XXX value on failure.
.
.
.Sh UNIT MANAGEMENT
.
.Ft "int"
.Fn "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
CUSE_ERR_XXX value on failure.
.
.Pp
.
.Ft "int"
.Fn "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
CUSE_ERR_XXX value on failure.
.
.Pp
.
.Ft "int"
.Fn "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.
.
.Pp
.
.Ft "int"
.Fn "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 CUSE_ERR_XXX value on failure.
.
.
.Sh LIBRARY USAGE
.
.
.Ft "void *"
.Fn "cuse_vmalloc" "int size"
This function allocates
.Ar 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.
.
.Pp
.
.Ft "void"
.Fn "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.
.
.
.Pp
.
.Ft "unsigned long"
.Fn "cuse_vmoffset" "void *"
This function returns the mmap offset that the client must use to
access the allocated memory.
.
.Pp
.
.Ft "struct cuse_dev *"
.Fn "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.
.
.Pp
.
.Ft "void"
.Fn "cuse_dev_destroy" "struct cuse_dev *"
This functions destroys a previously created character device.
.
.Pp
.
.
.Ft "void *"
.Fn "cuse_dev_get_priv0" "struct cuse_dev *"
,
.Ft "void *"
.Fn "cuse_dev_get_priv1" "struct cuse_dev *"
,
.Ft "void"
.Fn "cuse_dev_set_priv0" "struct cuse_dev *" "void *"
,
.Ft "void"
.Fn "cuse_dev_set_priv1" "struct cuse_dev *" "void *"
These functions are used to set and get the private data of the given
cuse device.
.
.Pp
.
.Ft "int"
.Fn "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 CUSE_ERR_XXX
value on failure.
.
.Pp
.
.Ft "void"
.Fn "cuse_dev_set_per_file_handle" "struct cuse_dev *" "void *"
,
.Ft "void *"
.Fn "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.
.
.Pp
.
.Ft "void"
.Fn "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.
.
.Pp
.
.Ft "int"
.Fn "cuse_copy_out" "const void *src" "void *peer_dst" "int len"
,
.Ft "int"
.Fn "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 returns
0 on success or a negative CUSE_ERR_XXX value on failure.
.
.Pp
.
.Ft "int"
.Fn "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.
.
.Pp
.
.Ft "struct cuse_dev *"
.Fn "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.
.
.Pp
.
.Ft "void"
.Fn "cuse_poll_wakeup" "void"
This function will wake up any file pollers.
.
.Pp
.
.Sh LIBRARY CALLBACK METHODS
.
In general fflags are defined by CUSE_FFLAG_XXX and errors are defined by CUSE_ERR_XXX.
.
.Bd -literal -offset indent
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
};
.Ed
.
.Pp
.
.Ft "int"
.Fn "cuse_open_t" "struct cuse_dev *" "int fflags"
This functions returns a CUSE_ERR_XXX value.
.
.Pp
.
.Ft "int"
.Fn "cuse_close_t" "struct cuse_dev *" "int fflags"
This functions returns a CUSE_ERR_XXX value.
.
.Pp
.
.Ft "int"
.Fn "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.
.
.Pp
.
.Ft "int"
.Fn "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.
.
.Pp
.
.Ft "int"
.Fn "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.
.
.Pp
.
.Ft "int"
.Fn "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.
.
.Pp
.
.Bd -literal -offset indent
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;
};
.Ed
.
.
.Sh SEE ALSO
.
.Sh HISTORY
.
.Nm
was written by Hans Petter Selasky .