Typedefs | Functions

le_fdMonitor.h File Reference

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.

    1 if (events & POLLIN)
    2 {
    3     // Data available to read.
    4     ...
    5 }
    6 
    7 if (events & POLLERR)
    8 {
    9     // An error occured.
   10     ...
   11 }
   12 
   13 ...
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]nameName of the object (for diagnostics).
[in]fdFile descriptor to be monitored for events.
[in]handlerFuncHandler function.
[in]eventsInitial set of events to be monitored.
void le_fdMonitor_Delete ( le_fdMonitor_Ref_t  monitorRef)

Deletes a file descriptor monitor object.

Parameters
[in]monitorRefReference 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]monitorRefReference to the File Descriptor Monitor object.
[in]eventsBit 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]monitorRefReference to the File Descriptor Monitor object.
[in]eventsBit 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]monitorRefReference 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]monitorRefReference to the File Descriptor Monitor.
[in]contextPtrOpaque 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]monitorRefReference to the File Descriptor Monitor object.
[in]isDeferrabletrue (deferrable) or false (urgent).