195 lines
6.7 KiB
Groff
195 lines
6.7 KiB
Groff
.\" $NetBSD: puffs_req.3,v 1.5 2007/12/01 19:54:01 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2007 Antti Kantee. 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 9, 2007
|
|
.Dt PUFFS_REQ 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm puffs_req
|
|
.Nd puffs request handling
|
|
.Sh LIBRARY
|
|
.Lb libpuffs
|
|
.Sh SYNOPSIS
|
|
.In puffs.h
|
|
.Ft struct puffs_getreq *
|
|
.Fn puffs_req_makeget "struct puffs_usermount *pu" "size_t buflen" "int maxops"
|
|
.Ft int
|
|
.Fn puffs_req_loadget "struct puffs_getreq *pgr"
|
|
.Ft struct puffs_req *
|
|
.Fn puffs_req_get "struct puffs_getreq *pgr"
|
|
.Ft int
|
|
.Fn puffs_req_remainingget "struct puffs_getreq *pgr"
|
|
.Ft void
|
|
.Fn puffs_req_setmaxget "struct puffs_getreq *pgr" "int maxops"
|
|
.Ft void
|
|
.Fn puffs_req_destroyget "struct puffs_getreq *pgr"
|
|
.Ft struct puffs_putreq *
|
|
.Fn puffs_req_makeput "struct puffs_usermount *pu"
|
|
.Ft void
|
|
.Fn puffs_req_put "struct puffs_putreq *ppr" "struct puffs_req *preq"
|
|
.Ft void
|
|
.Fn puffs_req_putcc "struct puffs_putreq *ppr" "struct puffs_cc *pcc"
|
|
.Ft int
|
|
.Fn puffs_req_putput "struct puffs_putreq *ppr"
|
|
.Ft void
|
|
.Fn puffs_req_resetput "struct puffs_putreq *ppr"
|
|
.Ft void
|
|
.Fn puffs_req_destroyput "struct puffs_putreq *ppr"
|
|
.Ft int
|
|
.Fo puffs_req_handle
|
|
.Fa "struct puffs_getreq *pgr" "struct puffs_putreq *ppr" "int maxops"
|
|
.Fc
|
|
.Ft int
|
|
.Fo puffs_dopreq
|
|
.Fa "struct puffs_usermount *pu" "struct puffs_req *preq"
|
|
.Fa "struct puffs_putreq *ppr"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
.Em IMPORTANT NOTE!
|
|
This document describes interfaces which are not yet guaranteed to be
|
|
stable.
|
|
In case you update your system sources, please recompile everything
|
|
and fix compilation errors.
|
|
If your sources are out-of-sync, incorrect operation may result.
|
|
The interfaces in this document will most likely be hugely simplified
|
|
in later versions or made transparent to the implementation.
|
|
THIS INTERFACE IS GUARANTEED TO CHANGE.
|
|
This will be to better accommodate memory allocation for call contexts.
|
|
.Pp
|
|
These function provide a way to communicate with the kernel.
|
|
They provide data storage and buffering.
|
|
There are two classes of request-handling functions:
|
|
the get-family works with requests incoming from the kernel and
|
|
the put-family is involved with storing the results and communicating
|
|
them back to the kernel.
|
|
.Pp
|
|
Data strorage for a get request is allocated with
|
|
.Fn puffs_req_makeget .
|
|
It will allocate
|
|
.Fa buflen
|
|
bytes of memory and set the maximum number of operations to be queried
|
|
from the kernel to
|
|
.Fa maxops .
|
|
A value of 0 means that the maximum number of opearations is limited by
|
|
buffer space and number of available incoming operations.
|
|
The maximum number can later be altered using
|
|
.Fn puffs_req_setmaxget .
|
|
.Pp
|
|
Operations are queried from the kernel into the buffer
|
|
.Fa pgr
|
|
by using
|
|
.Fn puffs_req_loadget .
|
|
The number of requests returned has an upper limit given by the
|
|
.Va maxops
|
|
associated with
|
|
.Fa pgr ,
|
|
but this might return fewer requests if there was not enough space
|
|
in the buffer or if fewer requests were available at the time of
|
|
the call.
|
|
In case at least one request is returned, the operation
|
|
is considered to be successful.
|
|
The function also resets any previous state in the buffer back to
|
|
what it would have been like immediate after the call to
|
|
.Fn puffs_req_makeget
|
|
prior to loading the new operations.
|
|
.Pp
|
|
After the request structure has been filled by
|
|
.Fn puffs_req_loadget ,
|
|
individual requests can be queried for with
|
|
.Fn puffs_req_get .
|
|
The best way to handle one is to pass it to
|
|
.Fn puffs_dopreq ,
|
|
which will decode the request, create a callcontext (cc), and call
|
|
the appropriate file system operation.
|
|
The number of requests remaining available for get is given by
|
|
.Fn puffs_req_remainingget .
|
|
.Pp
|
|
Resources associated with a request buffer are freed using
|
|
.Fn puffs_req_destroyget .
|
|
After this call the handle is invalid.
|
|
.Pp
|
|
Conversely,
|
|
.Fn puffs_req_makeput
|
|
creates a request buffer for storing information processed by the file
|
|
system and waiting delivery to the kernel.
|
|
.Pp
|
|
The functions
|
|
.Fn puffs_req_put
|
|
and
|
|
.Fn puffs_req_putcc
|
|
are queue up information from completed calls.
|
|
In case the request was handled by the framework, the latter should be used.
|
|
If it was manually decoded and a callcontext was never created, the former
|
|
can be used.
|
|
In almost all cases the proper method is to use the latter.
|
|
Note that only those operations which desire a reply should get
|
|
queued.
|
|
This can be tested by invoking
|
|
.Fn PUFFSOP_WANTREPLY
|
|
on the operation class found in
|
|
.Fa preq_opclass .
|
|
.Pp
|
|
The results will be fed to the kernel using
|
|
.Fn puffs_req_putput .
|
|
.Pp
|
|
The buffer is reset to a pristine state with
|
|
.Fn puffs_req_resetput .
|
|
Notice the dissymmetry with the get-case, where the buffer is
|
|
reset automatically.
|
|
.Pp
|
|
Resources allocated with the put-buffer are released using
|
|
.Fn puffs_req_destroyput
|
|
.Pp
|
|
To automatically handle a get-process cycle, a file system can opt to use
|
|
.Fn puffs_req_handle ,
|
|
which will fetch
|
|
.Fa maxops
|
|
operations from the kernel and process them.
|
|
The caller should them proceed to possibly add more results, perhaps
|
|
as a result of continuations which were able to finish, and then
|
|
call
|
|
.Fn puffs_req_putput
|
|
in the usual manner.
|
|
.Pp
|
|
The call
|
|
.Fn puffs_dopreq
|
|
processes the given request
|
|
.Fa preq
|
|
and stores the possible return value in
|
|
.Fa ppr .
|
|
It should be noted that this call might not return a result in case
|
|
the operation it calls decides to block with
|
|
.Fn puffs_cc_yield .
|
|
.Sh RETURN VALUES
|
|
These function return a valid pointer on success or
|
|
.Dv NULL
|
|
on failure.
|
|
Functions which return an integer will return \-1 on failure.
|
|
All failing calls will indicate the error by setting
|
|
.Va errno .
|
|
.Sh SEE ALSO
|
|
.Xr puffs 3 ,
|
|
.Xr puffs_cc 3
|