http://www.aros.org AROS-Exec AROS-Exec Archives Power2People
kitty mascottop logo menu

unixio_hidd

Index


--background-- aoHidd_UnixIO_Architecture aoHidd_UnixIO_Opener moHidd_UnixIO_AddInterrupt
moHidd_UnixIO_CloseFile moHidd_UnixIO_ClosePacket moHidd_UnixIO_IOControlFile moHidd_UnixIO_MemoryMap
moHidd_UnixIO_MemoryUnMap moHidd_UnixIO_OpenFile moHidd_UnixIO_OpenPacket moHidd_UnixIO_Poll
moHidd_UnixIO_ReadFile moHidd_UnixIO_RecvPacket moHidd_UnixIO_RemInterrupt moHidd_UnixIO_SendPacket
moHidd_UnixIO_Wait moHidd_UnixIO_WriteFile    

--background--

Notes

unixio.hidd is a simple driver for host-side I/O on UNIX system. Its primary
purpose is to handle non-blocking I/O on AROS task level. Also it provides
common file access operations (open, close, read, write and ioctl) in order
to avoid code duplication.

I/O operations you perform must never block. The whole AROS with all its tasks
is just one process from host OS' point of view, so blocking operation would
halt all the system. In order to avoid this you need to make sure that the
file descriptor is actually ready to perform I/O. If this is not the case,
your task needs to wait until file descriptor becomes available. unixio.hidd
offers a simple way of doing it by adding an interrupt handler to the file
descriptor using moHidd_UnixIO_AddInterrupt method. The interrupt handler
will be called whenever SIGIO arrives from the specified descriptor and specified
conditions are met. You do not need to explicitly enable asynchronous I/O
on the file descriptor, unixio.hidd takes care about all this itself.

There's also a convenience moHidd_UnixIO_Wait method. It allows you to simulate
a normal blocking I/O in a simple way.

Starting from v42 unixio.hidd is a singletone. This means that all calls to
OOP_NewObject() will actually return the same object which is never really
disposed. This object pointer can be freely transferred between tasks. It's
not necessary t call OOP_DisposeObject() on it. It is safe, but will do nothing.
Usage counter is maintained by OpenLibrary()/CloseLibrary() calls.

Remember that all values (like file mode flags and errno values) are host-specific!
Different hosts may use different values, and even different structure layouts
(especially this affects ioctl). When opening unixio.hidd it is adviced to check
that host OS matches what is expected (what your client program/driver/whatever
is compiled for). Use aoHidd_UnixIO_Architecture attribute for this.

aoHidd_UnixIO_Architecture

Synopsis

[I..], STRPTR

Function

Specifiers architecture name to match against current system's architecture.
Architecture name needs to be supplied in the form "arch-cpu", for example
"linux-ppc" or "darwin-i386". Usually this comes from a definition when
you compile your module.

Example

struct TagItem tags = {
    {aHidd_UnixIO_Opener, "tap.device"},
    {aHidd_UnixIO_Architecture, "linux-i386"},
    {TAG_DONE, 0}
};
uio = OOP_NewObject(CLID_Hidd_UnixIO, tags);
// If uio == NULL, the system you're running on is not linux-i386. The error
// requester has been already presented to the user.

Notes

This attribute allows you to ensure that your module is running on the same
architecture it was compiled for. This is needed because unixio.hidd by its
nature works with host OS structures and values (especially ioctl operation).
Different host OSes (for example Linux and Darwin) are not binary compatible
even on the same CPU. This is why the architecture check is generally needed,
especially for disk-based components.

It is adviced to specify your module name using aoHidd_UnixIO_Opener. This needed
in order to display the correct name to the user if the check fails, so the user
will see what module causes the error.

aoHidd_UnixIO_Opener

Synopsis

[I..], STRPTR

Function

Specifiers opener name for architecture check routine.

Notes

This attribute's sole purpose is to be presented to the user in an error requester
if the architecture check fails. For example if you specify "tap.device" here,
the user will see a requester telling that "This version of tap.device is built
for XXX architecture, while current system architecture is YYY".

If this attribute is not specified, but architecture check is requested using
aoHidd_UnixIO_Architecture, current task's name will be used. This can be not
always approptiate, so it's adviced to always specify your driver or program
name here.

moHidd_UnixIO_AddInterrupt

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_AddInterrupt *msg);

int Hidd_UnixIO_AddInterrupt(OOP_Object *obj, struct uioInterrupt *interrupt);

Function

Install a filedescriptor-specific event interrupt handler

Inputs

obj       - An pointer to a UnixIO object
interrupt - A pointer to an interrupt descriptor structure initialized as follows:
              fd          - Number of file descriptor to watch
              mode        - one or more of mode flags
              handler     - A pointer to a handler routine.
              handlerData - User-specified data for the interrupt handler

            The interrupt handler routine will be called using C calling convention:

            void handler(int fd, int mode, void *data)

            where:
              fd   - File descriptor number
              mode - Flags reflecting set of occured events
              data - User data (specified in handlerData member of uioInterrupt structure)

Result

Zero if interrupt was successfully installed and UNIX errno value if
there was an error during setting up the filedescriptor.

moHidd_UnixIO_CloseFile

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_CloseFile *msg);

int Hidd_UnixIO_CloseFile (OOP_Object *obj, int fd, int *errno_ptr);

Function

Close a UNIX file descriptor.

Inputs

obj       - A pointer to a UnixIO object.
fd        - A file descriptor to close.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
            errno variable) will be written.

Result

0 in case of success and -1 on failure.

Notes

Despite there's no return value, error code still can be set.

moHidd_UnixIO_ClosePacket

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_ClosePacket *msg);

int Hidd_UnixIO_ClosePacket (OOP_Object *obj, int fd, int *errno_ptr);

Function

Close a UNIX packet descriptor.

Inputs

obj       - A pointer to a UnixIO object.
pd        - A packet descriptor to close.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
            errno variable) will be written.

Result

0 in case of success and -1 on failure.

Notes

Despite there's no return value, error code still can be set.

moHidd_UnixIO_IOControlFile

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_IOControlFile *msg);

int Hidd_UnixIO_IOControlFile(OOP_Object *obj, int fd, int request, void *param, int *errno_ptr);

Function

Perform a special operation (ioctl) on a UNIX file descriptor.

Inputs

obj       - A pointer to a UnixIO object.
fd        - A file descriptor to operate on.
request   - A device-specific operation code.
param     - A pointer to a request-specific parameter block.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
            errno variable) will be written.

Result

Operation-specific value (actually a return value of ioctl() function called).

Notes

This method can be called from within interrupts.

moHidd_UnixIO_MemoryMap

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_MemoryMap *msg);

int Hidd_UnixIO_MemoryMap(OOP_Object *obj, OOP_Object *o, void *addr, int len, int prot, int flags, int fd, int offset, int *errno_ptr);

Function

Maps address into file descriptor.

Inputs

    obj   - A pointer to a UnixIO object.
    fd    - A file descriptor to check.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
        errno variable) will be written.

Result

Actuall mapping address or MAP_FAILED for errors.

Notes

This method can be called from within interrupts.

moHidd_UnixIO_MemoryUnMap

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_MemoryUnMap *msg);

int Hidd_UnixIO_MemoryUnMap(OOP_Object *obj, OOP_Object *o, void *addr, int len, int *errno_ptr);

Function

Unmaps memory

Inputs

    obj   - A pointer to a UnixIO object.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
        errno variable) will be written.

Result

0 for success, -1 for failure

Notes

This method can be called from within interrupts.

moHidd_UnixIO_OpenFile

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_OpenFile *msg);

int Hidd_UnixIO_OpenFile (OOP_Object *obj, const char *filename, int flags, int mode, int *errno_ptr);

Function

Open a UNIX file descriptor

Inputs

obj       - An pointer to a UnixIO object
filename  - File name to open. File name should meet host OS conventions.
flags     - Flags specifying open mode. These are the same flags as for
            open() C function. Note that this value is passed directly to
            the host OS, and its definition can differ from AROS one.
errno_ptr - An optional pointer to a location where error code (value of
            UNIX errno variable) will be written

Result

A number of the opened file descriptor or -1 for an error.

moHidd_UnixIO_OpenPacket

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_OpenPacket *msg);

int Hidd_UnixIO_OpenPacket (OOP_Object *obj, const char *Interface, int *errno_ptr);

Function

Open a UNIX packet descriptor to a raw network interface

Inputs

obj       - An pointer to a UnixIO object
interface - Name of a network interace (ie eth0)
errno_ptr - An optional pointer to a location where error code (value of
        UNIX errno variable) will be written

Result

A number of the opened packet descriptor or -1 for an error.

moHidd_UnixIO_Poll

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_Poll *msg);

int Hidd_UnixIO_Poll(OOP_Object *obj, int fd, int mode, int *errno_ptr);

Function

Check current status of UNIX file descriptor or -1 if an error occured.

Inputs

obj       - A pointer to a UnixIO object.
fd        - A file descriptor to check.
mode      - Mask of modes we are interested in.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
            errno variable) will be written.

Result

Current set of filedescriptor modes.

Notes

This method can be called from within interrupts.

moHidd_UnixIO_ReadFile

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_ReadFile *msg);

int Hidd_UnixIO_ReadFile(OOP_Object *obj, int fd, void *buffer, int count, int *errno_ptr);

Function

Read data from a UNIX file descriptor.

Inputs

obj       - A pointer to a UnixIO object.
fd        - A file descriptor to read from.
buffer    - A pointer to a buffer for data.
count     - Number of bytes to read.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
            errno variable) will be written.

Result

Number of bytes actually read or -1 if error happened.

Notes

If there's no errno pointer supplied read operation will be automatically repeated if one
of EINTR or EAGAIN error happens. If you supplied valid own errno_ptr you should be ready
to handle these conditions yourself.

This method can be called from within interrupts.

moHidd_UnixIO_RecvPacket

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_RecvPacket *msg);

int Hidd_UnixIO_RecvPacket(OOP_Object *obj, int fd, void *buffer, int count, int *errno_ptr);

Function

Read packet from a Unix packet descriptor

Inputs

obj       - A pointer to a UnixIO object.
pd        - A packet descriptor to read from.
buffer    - A pointer to a buffer for data.
count     - Number of bytes to read.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
            errno variable) will be written.

Result

Number of bytes actually read or -1 if error happened.

Notes

If there's no errno pointer supplied read operation will be automatically repeated if one
of EINTR or EAGAIN error happens. If you supplied valid own errno_ptr you should be ready
to handle these conditions yourself.

This method can be called from within interrupts.

moHidd_UnixIO_RemInterrupt

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_RemInterrupt *msg);

void Hidd_UnixIO_RemInterrupt(OOP_Object *obj, struct uioInterrupt *interrupt);

Function

Remove previously installed file descriptor event interrupt structure

Inputs

obj       - An pointer to a UnixIO object
interrupt - A pointer to a previously installed interrupt descriptor structure

Result

None.

moHidd_UnixIO_SendPacket

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_SendPacket *msg);

int Hidd_UnixIO_SendPacket(OOP_Object *obj, int fd, void *buffer, int count, int *errno_ptr);

Function

Write data to a UNIX packet descriptor.

Inputs

obj       - A pointer to a UnixIO object.
pd        - A packet descriptor to write to.
buffer    - A pointer to a buffer containing data.
count     - Number of bytes to write.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
            errno variable) will be written.

Result

Number of bytes actually written or -1 if error happened.

Notes

If there's no errno pointer supplied read operation will be automatically repeated if one
of EINTR or EAGAIN error happens. If you supplied valid own errno_ptr you should be ready
to handle these conditions yourself.

This method can be called from within interrupts.

moHidd_UnixIO_Wait

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_ *msg);

IPTR Hidd_UnixIO_Wait(OOP_Object *obj, ULONG fd, ULONG mode);

Function

Wait for an event on the file descriptor.

Inputs

obj          - A pointer to a UnixIO object
fd           - A file descriptor to wait on
mode         - A combination of two flags:
                - vHidd_UnixIO_Read  - to request waiting until read is permitted
                - vHidd_UnixIO_Write - to request waiting until write is permitted

Result

0 in case of success or UNIX errno value in case if the operation failed.

moHidd_UnixIO_WriteFile

Synopsis

OOP_DoMethod(OOP_Object *obj, struct pHidd_UnixIO_WriteFile *msg);

int Hidd_UnixIO_WriteFile(OOP_Object *obj, int fd, void *buffer, int count, int *errno_ptr);

Function

Write data to a UNIX file descriptor.

Inputs

obj       - A pointer to a UnixIO object.
fd        - A file descriptor to write to.
buffer    - A pointer to a buffer containing data.
count     - Number of bytes to write.
errno_ptr - An optional pointer to a location where error code (a value of UNIX
            errno variable) will be written.

Result

Number of bytes actually written or -1 if error happened.

Notes

If there's no errno pointer supplied read operation will be automatically repeated if one
of EINTR or EAGAIN error happens. If you supplied valid own errno_ptr you should be ready
to handle these conditions yourself.

This method can be called from within interrupts.

Copyright © 1995-2024, The AROS Development Team. All rights reserved.
Amiga®, AmigaOS®, Workbench and Intuition are trademarks of Amiga Inc. All other trademarks belong to their respective owners.