![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Index]](keyword_index.gif) |
![[Next]](next.gif) |
|
|
|
|
This chapter includes:
The io_read handler is responsible for returning data bytes to the client after receiving an _IO_READ message. Examples of functions that send this message are read(), readdir(), fread(), and fgetc(). Let's start by looking at the format of the message itself:
struct _io_read {
uint16_t type;
uint16_t combine_len;
int32_t nbytes;
uint32_t xtype;
};
typedef union {
struct _io_read i;
/* unsigned char data[nbytes]; */
/* nbytes is returned with MsgReply */
} io_read_t;
As with all resource manager messages, we've defined a union that contains the input (coming into the resource manager) structure and a reply or output (going back to the client) structure. The io_read handler is prototyped with an argument of io_read_t *msg — that's the pointer to the union containing the message.
Since this is a read(), the type member has the value _IO_READ. The items of interest in the input structure are:
We'll create an io_read handler that actually returns some data (the fixed string "Hello, world\n"). We'll use the OCB to keep track of our position within the buffer that we're returning to the client.
When we get the _IO_READ message, the nbytes member tells us exactly how many bytes the client wants to read. Suppose that the client issues:
read (fd, buf, 4096);
In this case, it's a simple matter to return our entire "Hello, world\n" string in the output buffer and tell the client that we're returning 13 bytes, i.e. the size of the string.
However, consider the case where the client is performing the following:
while (read (fd, &character, 1) != EOF) {
printf ("Got a character \"%c\"\n", character);
}
Granted, this isn't a terribly efficient way for the client to perform reads! In this case, we would get msg->i.nbytes set to 1 (the size of the buffer that the client wants to get). We can't simply return the entire string all at once to the client — we have to hand it out one character at a time. This is where the OCB's offset member comes into play.
Here's a complete io_read handler that correctly handles these cases:
#include <errno.h>
#include <stdio.h>
#include <stddef.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/iofunc.h>
#include <sys/dispatch.h>
int io_read (resmgr_context_t *ctp, io_read_t *msg, RESMGR_OCB_T *ocb);
static char *buffer = "Hello world\n";
static resmgr_connect_funcs_t connect_funcs;
static resmgr_io_funcs_t io_funcs;
static iofunc_attr_t attr;
main(int argc, char **argv)
{
/* declare variables we'll be using */
resmgr_attr_t resmgr_attr;
dispatch_t *dpp;
dispatch_context_t *ctp;
int id;
/* initialize dispatch interface */
if((dpp = dispatch_create()) == NULL) {
fprintf(stderr, "%s: Unable to allocate dispatch handle.\n",
argv[0]);
return EXIT_FAILURE;
}
/* initialize resource manager attributes */
memset(&resmgr_attr, 0, sizeof resmgr_attr);
resmgr_attr.nparts_max = 1;
resmgr_attr.msg_max_size = 2048;
/* initialize functions for handling messages */
iofunc_func_init(_RESMGR_CONNECT_NFUNCS, &connect_funcs,
_RESMGR_IO_NFUNCS, &io_funcs);
io_funcs.read = io_read;
/* initialize attribute structure used by the device */
iofunc_attr_init(&attr, S_IFNAM | 0666, 0, 0);
attr.nbytes = strlen(buffer)+1;
/* attach our device name */
if((id = resmgr_attach(dpp, &resmgr_attr, "/dev/sample", _FTYPE_ANY, 0,
&connect_funcs, &io_funcs, &attr)) == -1) {
fprintf(stderr, "%s: Unable to attach name.\n", argv[0]);
return EXIT_FAILURE;
}
/* allocate a context structure */
ctp = dispatch_context_alloc(dpp);
/* start the resource manager message loop */
while(1) {
if((ctp = dispatch_block(ctp)) == NULL) {
fprintf(stderr, "block error\n");
return EXIT_FAILURE;
}
dispatch_handler(ctp);
}
}
int
io_read (resmgr_context_t *ctp, io_read_t *msg, RESMGR_OCB_T *ocb)
{
int nleft;
int nbytes;
int nparts;
int status;
if ((status = iofunc_read_verify (ctp, msg, ocb, NULL)) != EOK)
return (status);
if ((msg->i.xtype & _IO_XTYPE_MASK) != _IO_XTYPE_NONE)
return (ENOSYS);
/*
* On all reads (first and subsequent), calculate
* how many bytes we can return to the client,
* based upon the number of bytes available (nleft)
* and the client's buffer size
*/
nleft = ocb->attr->nbytes - ocb->offset;
nbytes = min (msg->i.nbytes, nleft);
if (nbytes > 0) {
/* set up the return data IOV */
SETIOV (ctp->iov, buffer + ocb->offset, nbytes);
/* set up the number of bytes (returned by client's read()) */
_IO_SET_READ_NBYTES (ctp, nbytes);
/*
* advance the offset by the number of bytes
* returned to the client.
*/
ocb->offset += nbytes;
nparts = 1;
} else {
/*
* they've asked for zero bytes or they've already previously
* read everything
*/
_IO_SET_READ_NBYTES (ctp, 0);
nparts = 0;
}
/* mark the access time as invalid (we just accessed it) */
if (msg->i.nbytes > 0)
ocb->attr->flags |= IOFUNC_ATTR_ATIME;
return (_RESMGR_NPARTS (nparts));
}
The ocb maintains our context for us by storing the offset field, which gives us the position within the buffer, and by having a pointer to the attribute structure attr, which tells us how big the buffer actually is via its nbytes member.
Of course, we had to give the resource manager library the address of our io_read handler so that it knew to call it. So the code in main() where we had called iofunc_func_init() became:
/* initialize functions for handling messages */
iofunc_func_init(_RESMGR_CONNECT_NFUNCS, &connect_funcs,
_RESMGR_IO_NFUNCS, &io_funcs);
io_funcs.read = io_read;
We also needed to add the following to the area above main():
#include <errno.h>
#include <unistd.h>
int io_read (resmgr_context_t *ctp, io_read_t *msg, RESMGR_OCB_T *ocb);
static char *buffer = "Hello world\n";"
Where did the attribute structure's nbytes member get filled in? In main(), just after we did the iofunc_attr_init(). We modified main() slightly:
After this line:
iofunc_attr_init (&attr, S_IFNAM | 0666, 0, 0);
We added this one:
attr.nbytes = strlen (buffer)+1;
At this point, if you were to run the resource manager (our simple resource manager used the name /dev/sample), you could do:
# cat /dev/sample Hello, world
The return line (_RESMGR_NPARTS(nparts)) tells the resource manager library to:
Where does it get the IOV array? It's using ctp->iov. That's why we first used the SETIOV() macro to make ctp->iov point to the data to reply with.
If we had no data, as would be the case of a read of zero bytes, then we'd do a return (_RESMGR_NPARTS(0)). But read() returns with the number of bytes successfully read. Where did we give it this information? That's what the _IO_SET_READ_NBYTES() macro was for. It takes the nbytes that we give it and stores it in the context structure (ctp). Then when we return to the library, the library takes this nbytes and passes it as the second parameter to the MsgReplyv(). The second parameter tells the kernel what the MsgSend() should return. And since the read() function is calling MsgSend(), that's where it finds out how many bytes were read.
We also update the access time for this device in the read handler. For details on updating the access time, see the section on “Updating the time for reads and writes” below.
The io_write handler is responsible for writing data bytes to the media after receiving a client's _IO_WRITE message. Examples of functions that send this message are write() and fflush(). Here's the message:
struct _io_write {
uint16_t type;
uint16_t combine_len;
int32_t nbytes;
uint32_t xtype;
/* unsigned char data[nbytes]; */
};
typedef union {
struct _io_write i;
/* nbytes is returned with MsgReply */
} io_write_t;
As with the io_read_t, we have a union of an input and an output message, with the output message being empty (the number of bytes actually written is returned by the resource manager library directly to the client's MsgSend()).
The data being written by the client almost always follows the header message stored in struct _io_write. The exception is if the write was done using pwrite() or pwrite64(). More on this when we discuss the xtype member.
To access the data, we recommend that you reread it into your own buffer. Let's say you had a buffer called inbuf that was “big enough” to hold all the data you expected to read from the client (if it isn't big enough, you'll have to read the data piecemeal).
The following is a code snippet that can be added to one of the simple resource manager examples. It prints out whatever it's given (making the assumption that it's given only character text):
int
io_write (resmgr_context_t *ctp, io_write_t *msg, RESMGR_OCB_T *ocb)
{
int status;
char *buf;
if ((status = iofunc_write_verify(ctp, msg, ocb, NULL)) != EOK)
return (status);
if ((msg->i.xtype & _IO_XTYPE_MASK) != _IO_XTYPE_NONE)
return(ENOSYS);
/* set up the number of bytes (returned by client's write()) */
_IO_SET_WRITE_NBYTES (ctp, msg->i.nbytes);
buf = (char *) malloc(msg->i.nbytes + 1);
if (buf == NULL)
return(ENOMEM);
/*
* Reread the data from the sender's message buffer.
* We're not assuming that all of the data fit into the
* resource manager library's receive buffer.
*/
resmgr_msgread(ctp, buf, msg->i.nbytes, sizeof(msg->i));
buf [msg->i.nbytes] = '\0'; /* just in case the text is not NULL terminated */
printf ("Received %d bytes = '%s'\n", msg -> i.nbytes, buf);
free(buf);
if (msg->i.nbytes > 0)
ocb->attr->flags |= IOFUNC_ATTR_MTIME | IOFUNC_ATTR_CTIME;
return (_RESMGR_NPARTS (0));
}
Of course, we'll have to give the resource manager library the address of our io_write handler so that it'll know to call it. In the code for main() where we called iofunc_func_init(), we'll add a line to register our io_write handler:
/* initialize functions for handling messages */
iofunc_func_init(_RESMGR_CONNECT_NFUNCS, &connect_funcs,
_RESMGR_IO_NFUNCS, &io_funcs);
io_funcs.write = io_write;
You may also need to add the following prototype:
int io_write (resmgr_context_t *ctp, io_write_t *msg,
RESMGR_OCB_T *ocb);
At this point, if you were to run the resource manager (our simple resource manager used the name /dev/sample), you could write to it by doing echo Hello > /dev/sample as follows:
# echo Hello > /dev/sample Received 6 bytes = 'Hello'
Notice how we passed the last argument to resmgr_msgread() (the offset argument) as the size of the input message buffer. This effectively skips over the header and gets to the data component.
If the buffer you supplied wasn't big enough to contain the entire message from the client (e.g. you had a 4 KB buffer and the client wanted to write 1 megabyte), you'd have to read the buffer in stages, using a for loop, advancing the offset passed to resmgr_msgread() by the amount read each time.
Unlike the io_read handler sample, this time we didn't do anything with ocb->offset. In this case there's no reason to. The ocb->offset would make more sense if we were managing things that had advancing positions such as a file position.
The reply is simpler than with the io_read handler, since a write() call doesn't expect any data back. Instead, it just wants to know if the write succeeded and if so, how many bytes were written. To tell it how many bytes were written we used the _IO_SET_WRITE_NBYTES() macro. It takes the nbytes that we give it and stores it in the context structure (ctp). Then when we return to the library, the library takes this nbytes and passes it as the second parameter to the MsgReplyv(). The second parameter tells the kernel what the MsgSend() should return. And since the write() function is calling MsgSend(), that's where it finds out how many bytes were written.
Since we're writing to the device, we should also update the modification, and potentially, the creation time. For details on updating the modification and change of file status times, see the section on “Updating the time for reads and writes” below.
You can return to the resource manager library from your handler functions in various ways. This is complicated by the fact that the resource manager library can reply for you if you want it to, but you must tell it to do so and put the information that it'll use in all the right places.
In this section, we'll discuss the following ways of returning to the resource manager library:
To reply to the client such that the function the client is calling (e.g. read()) will return with an error, you simply return with an appropriate errno value (from <errno.h>).
return (ENOMEM);
In the case of a read(), this causes the read to return -1 with errno set to ENOMEM.
 |
You might sometimes see this in the code for a resource manager:
_RESMGR_ERRNO (error_code) but this is the same as simply returning the error_code directly. The _RESMGR_ERRNO() macro is deprecated. |
Sometimes you'll want to reply with a header followed by one of N buffers, where the buffer used will differ each time you reply. To do this, you can set up an IOV array whose elements point to the header and to a buffer.
The context structure already has an IOV array. If you want the resource manager library to do your reply for you, then you must use this array. But the array must contain enough elements for your needs. To ensure that this is the case, set the nparts_max member of the resmgr_attr_t structure that you passed to resmgr_attach() when you registered your name in the pathname space.
The following example assumes that the variable i contains the offset into the array of buffers of the desired buffer to reply with. The 2 in _RESMGR_NPARTS(2) tells the library how many elements in ctp->iov to reply with.
my_header_t header; a_buffer_t buffers[N]; ... SETIOV(&ctp->iov[0], &header, sizeof(header)); SETIOV(&ctp->iov[1], &buffers[i], sizeof(buffers[i])); return (_RESMGR_NPARTS(2));
An example of this would be replying to a read() where all the data existed in a single buffer. You'll typically see this done in two ways:
return (_RESMGR_PTR(ctp, buffer, nbytes));
And:
SETIOV (ctp->iov, buffer, nbytes); return (_RESMGR_NPARTS(1));
The first method, using the _RESMGR_PTR() macro, is just a convenience for the second method where a single IOV is returned.
This can be done in a few ways. The most simple would be:
return (EOK);
But you'll often see:
return (_RESMGR_NPARTS(0));
Note that in neither case are you causing the MsgSend() to return with a 0. The value that the MsgSend() returns is the value passed to the _IO_SET_READ_NBYTES(), _IO_SET_WRITE_NBYTES(), and other similar macros. These two were used in the read and write samples above.
In this case, you give the client the data and get the resource manager library to do the reply for you. However, the reply data won't be valid by that time. For example, if the reply data was in a buffer that you wanted to free before returning, you could use the following:
resmgr_msgwrite (ctp, buffer, nbytes, 0); free (buffer); return (EOK);
The resmgr_msgwrite() function copies the contents of buffer into the client's reply buffer immediately. Note that a reply is still required in order to unblock the client so it can examine the data. Next we free the buffer. Finally, we return to the resource manager library such that it does a reply with zero-length data. Since the reply is of zero length, it doesn't overwrite the data already written into the client's reply buffer. When the client returns from its send call, the data is there waiting for it.
In all of the previous examples, it's the resource manager library that calls MsgReply*() or MsgError() to unblock the client. In some cases, you may not want the library to reply for you. For instance, you might have already done the reply yourself, or you'll reply later. In either case, you'd return as follows:
return (_RESMGR_NOREPLY);
An example of a resource manager that would reply to clients later is a pipe resource manager. If the client is doing a read of your pipe but you have no data for the client, then you have a choice:
Or:
Another example might be if the client wants you to write to some device but doesn't want to get a reply until the data has been fully written out. Here are the sequence of events that might follow:
The first issue, though, is whether the client wants to be left blocked. If the client doesn't want to be left blocked, then it opens with the O_NONBLOCK flag:
fd = open("/dev/sample", O_RDWR | O_NONBLOCK);
The default is to allow you to block it.
One of the first things done in the read and write samples above was to call some POSIX verification functions: iofunc_read_verify() and iofunc_write_verify(). If we pass the address of an int as the last parameter, then on return the functions will stuff that int with nonzero if the client doesn't want to be blocked (O_NONBLOCK flag was set) or with zero if the client wants to be blocked.
int nonblock;
if ((status = iofunc_read_verify (ctp, msg, ocb,
&nonblock)) != EOK)
return (status);
...
int nonblock;
if ((status = iofunc_write_verify (ctp, msg, ocb,
&nonblock)) != EOK)
return (status);
When it then comes time to decide if we should reply with an error or reply later, we do:
if (nonblock) {
/* client doesn't want to be blocked */
return (EAGAIN);
} else {
/*
* The client is willing to be blocked.
* Save at least the ctp->rcvid so that you can
* reply to it later.
*/
...
return (_RESMGR_NOREPLY);
}
The question remains: How do you do the reply yourself? The only detail to be aware of is that the rcvid to reply to is ctp->rcvid. If you're replying later, then you'd save ctp->rcvid and use the saved value in your reply:
MsgReply(saved_rcvid, 0, buffer, nbytes);
Or:
iov_t iov[2]; SETIOV(&iov[0], &header, sizeof(header)); SETIOV(&iov[1], &buffers[i], sizeof(buffers[i])); MsgReplyv(saved_rcvid, 0, iov, 2);
Note that you can fill up the client's reply buffer as data becomes available by using resmgr_msgwrite() and resmgr_msgwritev(). Just remember to do the MsgReply*() at some time to unblock the client.
|
If you're replying to an _IO_READ or _IO_WRITE message, the status argument for MsgReply*() must be the number of bytes read or written. |
There's another way to resume the blocked operation, but it isn't as efficient as the other methods: you can call resmgr_msg_again(). This function restores the resmgr_context_t structure to the way it was when your resource manager received the message associated with the rcvid, and then processes the message again as if it had just been received.
The default action in most cases is for the library to cause the client's function to fail with ENOSYS:
return (_RESMGR_DEFAULT);
Topics in this session include:
The message structures passed to the io_read, io_write, and io_openfd handlers contain a member called xtype. From struct _io_read:
struct _io_read {
...
uint32_t xtype;
...
}
Basically, the xtype contains extended type information that can be used to adjust the behavior of a standard I/O function. Most resource managers care about only a few values:
For example:
struct myread_offset {
struct _io_read read;
struct _xtype_offset offset;
}
Some resource managers can be sure that their clients will never call pread*() or pwrite*(). (For example, a resource manager that's controlling a robot arm probably wouldn't care.) In this case, you can treat this type of message as an error.
struct myreadcond {
struct _io_read read;
struct _xtype_readcond cond;
}
As with _IO_XTYPE_OFFSET, if your resource manager isn't prepared to handle readcond(), you can treat this type of message as an error.
The following code sample demonstrates how to handle the case where you're not expecting any extended types. In this case, if you get a message that contains an xtype, you should reply with ENOSYS. The example can be used in either an io_read or io_write handler.
int
io_read (resmgr_context_t *ctp, io_read_t *msg,
RESMGR_OCB_T *ocb)
{
int status;
if ((status = iofunc_read_verify(ctp, msg, ocb, NULL))
!= EOK) {
return (status);
}
/* No special xtypes */
if ((msg->i.xtype & _IO_XTYPE_MASK) != _IO_XTYPE_NONE)
return (ENOSYS);
...
}
Here are code examples that demonstrate how to handle an _IO_READ or _IO_WRITE message when a client calls:
The following sample code demonstrates how to handle _IO_READ for the case where the client calls one of the pread*() functions.
/* we are defining io_pread_t here to make the code below
simple */
typedef struct {
struct _io_read read;
struct _xtype_offset offset;
} io_pread_t;
int
io_read (resmgr_context_t *ctp, io_read_t *msg,
RESMGR_OCB_T *ocb)
{
off64_t offset; /* where to read from */
int status;
if ((status = iofunc_read_verify(ctp, msg, ocb, NULL))
!= EOK) {
return(status);
}
switch(msg->i.xtype & _IO_XTYPE_MASK) {
case _IO_XTYPE_NONE:
offset = ocb->offset;
break;
case _IO_XTYPE_OFFSET:
/*
* io_pread_t is defined above.
* Client is doing a one-shot read to this offset by
* calling one of the pread*() functions
*/
offset = ((io_pread_t *) msg)->offset.offset;
break;
default:
return(ENOSYS);
}
...
}
The following sample code demonstrates how to handle _IO_WRITE for the case where the client calls one of the pwrite*() functions. Keep in mind that the struct _xtype_offset information follows the struct _io_write in the sender's message buffer. This means that the data to be written follows the struct _xtype_offset information (instead of the normal case where it follows the struct _io_write). So, you must take this into account when doing the resmgr_msgread() call in order to get the data from the sender's message buffer.
/* we are defining io_pwrite_t here to make the code below
simple */
typedef struct {
struct _io_write write;
struct _xtype_offset offset;
} io_pwrite_t;
int
io_write (resmgr_context_t *ctp, io_write_t *msg,
RESMGR_OCB_T *ocb)
{
off64_t offset; /* where to write */
int status;
size_t skip; /* offset into msg to where the data
resides */
if ((status = iofunc_write_verify(ctp, msg, ocb, NULL))
!= EOK) {
return(status);
}
switch(msg->i.xtype & _IO_XTYPE_MASK) {
case _IO_XTYPE_NONE:
offset = ocb->offset;
skip = sizeof(io_write_t);
break;
case _IO_XTYPE_OFFSET:
/*
* io_pwrite_t is defined above
* client is doing a one-shot write to this offset by
* calling one of the pwrite*() functions
*/
offset = ((io_pwrite_t *) msg)->offset.offset;
skip = sizeof(io_pwrite_t);
break;
default:
return(ENOSYS);
}
...
/*
* get the data from the sender's message buffer,
* skipping all possible header information
*/
resmgr_msgreadv(ctp, iovs, niovs, skip);
...
}
The same type of operation that was done to handle the pread()/_IO_XTYPE_OFFSET case can be used for handling the client's readcond() call:
typedef struct {
struct _io_read read;
struct _xtype_readcond cond;
} io_readcond_t
Then:
struct _xtype_readcond *cond
...
CASE _IO_XTYPE_READCOND:
cond = &((io_readcond_t *)msg)->cond
break;
}
Then your manager has to properly interpret and deal with the arguments to readcond(). For more information, see the QNX Neutrino Library Reference.
In the read sample above we did:
if (msg->i.nbytes > 0)
ocb->attr->flags |= IOFUNC_ATTR_ATIME;
According to POSIX, if the read succeeds and the reader had asked for more than zero bytes, then the access time must be marked for update. But POSIX doesn't say that it must be updated right away. If you're doing many reads, you may not want to read the time from the kernel for every read. In the code above, we mark the time only as needing to be updated. When the next _IO_STAT or _IO_CLOSE_OCB message is processed, the resource manager library will see that the time needs to be updated and will get it from the kernel then. This of course has the disadvantage that the time is not the time of the read.
Similarly for the write sample above, we did:
if (msg->i.nbytes > 0)
ocb->attr->flags |= IOFUNC_ATTR_MTIME | IOFUNC_ATTR_CTIME;
so the same thing will happen.
If you do want to have the times represent the read or write times, then after setting the flags you need only call the iofunc_time_update() helper function. So the read lines become:
if (msg->i.nbytes > 0) {
ocb->attr->flags |= IOFUNC_ATTR_ATIME;
iofunc_time_update(ocb->attr);
}
and the write lines become:
if (msg->i.nbytes > 0) {
ocb->attr->flags |= IOFUNC_ATTR_MTIME | IOFUNC_ATTR_CTIME;
iofunc_time_update(ocb->attr);
}
You should call iofunc_time_update() before you flush out any cached attributes. As a result of changing the time fields, the attribute structure will have the IOFUNC_ATTR_DIRTY_TIME bit set in the flags field, indicating that this field of the attribute must be updated when the attribute is flushed from the cache.
|
|
|
|