SVR5
copyout(D3)
copyout --
copy data from a driver buffer to a user buffer
Synopsis
#include <sys/types.h>
#include <sys/ddi.h>
int copyout(void * driverbuf, void * userbuf, size_t count);
Description
copyout copies count bytes of data from the kernel virtual
address specified by driverbuf to the user virtual address
specified by userbuf.
Arguments
driverbuf-
Driver source address from which copy is made.
userbuf-
User destination address to which copy is made.
count-
Number of bytes to copy.
Return values
On success, copyout returns 0.
On failure, it returns -1 to indicate that the specified user address
range is not valid.
Usage
copyout chooses the best algorithm
based on address alignment and number of bytes to copy.
Although the source and destination addresses are not required to be word
aligned, word aligned addresses may result in a more efficient copy.
Drivers usually convert a return value of -1 into an EFAULT error.
Context and synchronization
User
context.
Warnings
The driver source buffer
must be completely within the kernel address space,
or the system can panic.
When holding sleep locks across calls to this function,
drivers must be careful to avoid creating a deadlock.
During the data transfer, page fault resolution
might result in another I/O to the same device.
For example, this could occur
if the driver controls the disk drive used as the swap device.
Examples
A driver
ioctl(D2)
routine (line 5)
can be used to get or set device attributes or registers.
If the specified command is XX_GETREGS (line 9),
the driver copies the current device
register values to a user data area (line 11).
If the user address is invalid,
an error code is returned.
1 struct device { /* device registers layout */
...
2 int status; /* device status word */
3 };
4 struct idata { /* instance data */
5 ...
6 struct device *devregs;
...
7 }
...
8 xxioctl(void *idata, ulong_t channel, int cmd, void *arg, int mode, cred_t *crp, int *rvp)
9 {
10 struct device *dp;
11 switch (cmd) {
12 case XX_GETREGS: /* copy device registers to user program */
13 dp = ((struct idata *)idata)->devregs;
14 if (copyout(dp, arg, sizeof(struct device)))
15 return (EFAULT);
16 break;
Hardware applicability
All
Version applicability
ddi:
1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp, 8, 8mp
SCO OpenServer ODDI compatibility
copyout(D3oddi)
is the ODDI equivalent of this function.
ODDI also supports other functions
for moving data between user and kernel space; see
``Data, copying'' in HDK Technical Reference
for more information.
References
bcopy(D3),
copyin(D3),
uiomove(D3),
ureadc(D3),
uwritec(D3)
M_COPYOUT(D7str)
``Data, copying'' in HDK Technical Reference
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005