Go to the source code of this file.
Typedefs | |
typedef struct le_fdMonitor * | le_fdMonitor_Ref_t |
typedef void(* | le_fdMonitor_HandlerFunc_t) (int fd, short events) |
Functions | |
le_fdMonitor_Ref_t | le_fdMonitor_Create (const char *name, int fd, le_fdMonitor_HandlerFunc_t handlerFunc, short events) |
void | le_fdMonitor_Enable (le_fdMonitor_Ref_t monitorRef, short events) |
void | le_fdMonitor_Disable (le_fdMonitor_Ref_t monitorRef, short events) |
void | le_fdMonitor_SetDeferrable (le_fdMonitor_Ref_t monitorRef, bool isDeferrable) |
void | le_fdMonitor_SetContextPtr (le_fdMonitor_Ref_t monitorRef, void *contextPtr) |
void * | le_fdMonitor_GetContextPtr (void) |
int | le_fdMonitor_GetFd (le_fdMonitor_Ref_t monitorRef) |
le_fdMonitor_Ref_t | le_fdMonitor_GetMonitor (void) |
void | le_fdMonitor_Delete (le_fdMonitor_Ref_t monitorRef) |
Detailed Description
Legato File Descriptor Monitor API include file.
Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
Typedef Documentation
typedef void(* le_fdMonitor_HandlerFunc_t) (int fd, short events) |
Prototype for file descriptor event handler functions.
Events that can be received:
POLLIN
= Data available to read.POLLPRI
= Urgent data available to read (e.g., out-of-band data on a socket).POLLOUT
= Writing to the fd should accept some data now.POLLRDHUP
= Other end of stream socket closed or shutdown.POLLERR
= Error occurred.POLLHUP
= Hang up.
These are bitmask values that may appear in the events
parameter. Use the bit-wise AND operator ('&') to test for specific events.
- Parameters
-
fd [in] File descriptor. events [in] Bit map of events that occurred. Use bitwise AND ('&') to test for events.
typedef struct le_fdMonitor* le_fdMonitor_Ref_t |
File Descriptor Monitor reference.
Used to refer to File Descriptor Monitor objects.
Function Documentation
le_fdMonitor_Ref_t le_fdMonitor_Create | ( | const char * | name, |
int | fd, | ||
le_fdMonitor_HandlerFunc_t | handlerFunc, | ||
short | events | ||
) |
Creates a File Descriptor Monitor.
Creates an object that will monitor a given file descriptor for events.
The monitoring will be performed by the event loop of the thread that created the Monitor object. If that thread is blocked, no events will be detected for that file descriptor until that thread is unblocked and returns to its event loop.
Events that can be enabled for monitoring:
POLLIN
= Data available to read.POLLPRI
= Urgent data available to read (e.g., out-of-band data on a socket).POLLOUT
= Writing to the fd should accept some data now.
These are bitmask values and can be combined using the bit-wise OR operator ('|').
The following events are always monitored, even if not requested:
POLLRDHUP
= Other end of stream socket closed or shutdown.POLLERR
= Error occurred.POLLHUP
= Hang up.
- Returns
- Reference to the object, which is needed for later deletion.
- Note
- Doesn't return on failure, there's no need to check the return value for errors.
- Parameters
-
[in] name Name of the object (for diagnostics). [in] fd File descriptor to be monitored for events. [in] handlerFunc Handler function. [in] events Initial set of events to be monitored.
void le_fdMonitor_Delete | ( | le_fdMonitor_Ref_t | monitorRef | ) |
Deletes a file descriptor monitor object.
- Parameters
-
[in] monitorRef Reference to the File Descriptor Monitor object.
void le_fdMonitor_Disable | ( | le_fdMonitor_Ref_t | monitorRef, |
short | events | ||
) |
Disables monitoring for events on a file descriptor.
Events that can be disabled for monitoring:
POLLIN
= Data available to read.POLLPRI
= Urgent data available to read (e.g., out-of-band data on a socket).POLLOUT
= Writing to the fd should accept some data now.
These are bitmask values and can be combined using the bit-wise OR operator ('|').
- Parameters
-
[in] monitorRef Reference to the File Descriptor Monitor object. [in] events Bit map of events.
void le_fdMonitor_Enable | ( | le_fdMonitor_Ref_t | monitorRef, |
short | events | ||
) |
Enables monitoring for events on a file descriptor.
Events that can be enabled for monitoring:
POLLIN
= Data available to read.POLLPRI
= Urgent data available to read (e.g., out-of-band data on a socket).POLLOUT
= Writing to the fd should accept some data now.
These are bitmask values and can be combined using the bit-wise OR operator ('|').
- Parameters
-
[in] monitorRef Reference to the File Descriptor Monitor object. [in] events Bit map of events.
void* le_fdMonitor_GetContextPtr | ( | void | ) |
Gets the Context Pointer for File Descriptor Monitor's handler function.
- Returns
- The context pointer set using le_fdMonitor_SetContextPtr(), or NULL if it hasn't been set.
- Note
- This only works inside the handler function. The difference between this function and le_event_GetContextPtr() is that le_fdMonitor_GetContextPtr() will double check that it's being called inside of a File Descriptor Monitor's handler function.
int le_fdMonitor_GetFd | ( | le_fdMonitor_Ref_t | monitorRef | ) |
Gets the file descriptor that an FD Monitor object is monitoring.
- Returns
- The fd.
- Parameters
-
[in] monitorRef Reference to the File Descriptor Monitor.
le_fdMonitor_Ref_t le_fdMonitor_GetMonitor | ( | void | ) |
Gets a reference to the File Descriptor Monitor whose handler function is currently running.
- Returns
- File Descriptor Monitor reference.
- Note
- This only works inside the handler function.
void le_fdMonitor_SetContextPtr | ( | le_fdMonitor_Ref_t | monitorRef, |
void * | contextPtr | ||
) |
Sets the Context Pointer for File Descriptor Monitor's handler function. This can be retrieved by the handler using le_fdMonitor_GetContextPtr() (or le_event_GetContextPtr()) when the handler function is running.
- Parameters
-
[in] monitorRef Reference to the File Descriptor Monitor. [in] contextPtr Opaque context pointer value.
void le_fdMonitor_SetDeferrable | ( | le_fdMonitor_Ref_t | monitorRef, |
bool | isDeferrable | ||
) |
Sets if processing of events on a given fd is deferrable (the system is allowed to go to sleep while there are monitored events pending for this fd) or urgent (the system will be kept awake until there are no monitored events waiting to be handled for this fd).
If the process has CAP_EPOLLWAKEUP
(or CAP_BLOCK_SUSPEND
) capability, then fd events are considered urgent by default.
If the process doesn't have CAP_EPOLLWAKEUP
(or CAP_BLOCK_SUSPEND
) capability, then fd events are always deferrable, and calls to this function have no effect.
- Parameters
-
[in] monitorRef Reference to the File Descriptor Monitor object. [in] isDeferrable true (deferrable) or false (urgent).