File Descriptor Handling Functions

- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

Typedefs | Enumerations | Functions
File Descriptor Handling Functions
Ecore » Ecore main loop

Definition for functions that deal with file descriptor handlers. More...

## Typedefs
typedef struct _Ecore_Fd_Handler | Ecore_Fd_Handler
| A handle for Fd handlers.
typedef enum _Ecore_Fd_Handler_Flags | Ecore_Fd_Handler_Flags
typedef Eina_Bool(* | Ecore_Fd_Cb) (void *data, Ecore_Fd_Handler *fd_handler)
| A callback used by an Ecore_Fd_Handler.
typedef void(* | Ecore_Fd_Prep_Cb) (void *data, Ecore_Fd_Handler *fd_handler)
| A callback used by an Ecore_Fd_Handler.
typedef Eina_Bool(* | Ecore_Win32_Handle_Cb) (void *data, Ecore_Win32_Handler *wh)
| A callback used by an Ecore_Win32_Handler.

## Enumerations
enum | _Ecore_Fd_Handler_Flags { ECORE_FD_READ = 1 , ECORE_FD_WRITE = 2 , ECORE_FD_ERROR = 4 , ECORE_FD_ALWAYS = 8 }
| What to monitor the file descriptor for: reading, writing or error. More...

## Functions
Ecore_Fd_Handler * | ecore_main_fd_handler_add (int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data)
| Adds a callback for activity on the given file descriptor.
Ecore_Fd_Handler * | ecore_main_fd_handler_file_add (int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data)
| Adds a callback for activity on the given file descriptor.
void | ecore_main_fd_handler_prepare_callback_set (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Prep_Cb func, const void *data)
| Sets the prepare callback with data for a given Ecore_Fd_Handler.
void * | ecore_main_fd_handler_del (Ecore_Fd_Handler *fd_handler)
| Marks an FD handler for deletion.
int | ecore_main_fd_handler_fd_get (Ecore_Fd_Handler *fd_handler)
| Retrieves the file descriptor that the given handler is handling.
Eina_Bool | ecore_main_fd_handler_active_get (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags)
| Gets which flags are active on an FD handler.
void | ecore_main_fd_handler_active_set (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags)
| Sets what active streams the given FD handler should be monitoring.
Ecore_Win32_Handler * | ecore_main_win32_handler_add (void *h, Ecore_Win32_Handle_Cb func, const void *data)
| Creates a Ecore_Win32_Handler object and add it to the win32_handlers list.
void * | ecore_main_win32_handler_del (Ecore_Win32_Handler *win32_handler)
| Sets Ecore_Win32_Handler object to delete state.

## Detailed Description

Definition for functions that deal with file descriptor handlers.

File descriptor handlers facilitate reading, writing and checking for errors without blocking the program or doing expensive pooling. This can be used to monitor a socket, pipe, or other stream for which an FD can be had.

Warning
  File descriptor handlers can't be used to monitor for file creation, modification or deletion, see Ecore_File - Files and directories convenience functions for this.

One common FD to be monitored is the standard input(stdin), monitoring it for reading requires a single call:

static Eina_Bool
_my_cb_func(void *data, Ecore_Fd_Handler *handler)
{
char c;
scanf("%c", &c); //Guaranteed not to block
... do stuff with c ...
}
ecore_main_fd_handler_add(STDIN_FILENO, ECORE_FD_READ, _my_cb_func, NULL, NULL, NULL);
Ecore_Fd_Handler
struct _Ecore_Fd_Handler Ecore_Fd_Handler
A handle for Fd handlers.
Definition: Ecore_Common.h:1380
ecore_main_fd_handler_add
Ecore_Fd_Handler * ecore_main_fd_handler_add(int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data)
Adds a callback for activity on the given file descriptor.
Definition: ecore_main.c:1449
ECORE_FD_READ
@ ECORE_FD_READ
Fd Read mask.
Definition: Ecore_Common.h:1388
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition: eina_types.h:527

When using a socket, pipe or other stream it's important to remember that errors may occur and as such to monitor not only for reading/writing but also for errors using the ECORE_FD_ERROR flag.

Example of use of a file descriptor handler:

- ecore fd handlers - Monitoring file descriptors

## Enumeration Type Documentation

## ◆ _Ecore_Fd_Handler_Flags

enum _Ecore_Fd_Handler_Flags

What to monitor the file descriptor for: reading, writing or error.

Enumerator
ECORE_FD_READ | Fd Read mask.
ECORE_FD_WRITE | Fd Write mask.
ECORE_FD_ERROR | Fd Error mask.
ECORE_FD_ALWAYS | Fd Always mask - DO NOT USE!

## Function Documentation

## ◆ ecore_main_fd_handler_add()

Ecore_Fd_Handler * ecore_main_fd_handler_add | ( | int | fd,
|  | Ecore_Fd_Handler_Flags | flags,
|  | Ecore_Fd_Cb | func,
|  | const void * | data,
|  | Ecore_Fd_Cb | buf_func,
|  | const void * | buf_data
| ) |  |

Adds a callback for activity on the given file descriptor.

Parameters

  fd | The file descriptor to watch.
  flags | To monitor it for reading use `ECORE_FD_READ`, for writing `ECORE_FD_WRITE`, and for error `ECORE_FD_ERROR`. Values by |(ored).
  func | The callback function.
  data | The data to pass to the callback.
  buf_func | The function to call to check if any data has been buffered and already read from the fd. May be `NULL`.
  buf_data | The data to pass to the `buf_func` function.

Returns
  A fd handler handle on success, `NULL` otherwise.

func will be called during the execution of The Ecore Main Loop when the file descriptor is available for reading, writing, or there has been an error(depending on the given flags).

When func returns `ECORE_CALLBACK_CANCEL`, it indicates that the handler should be marked for deletion (identical to calling ecore_main_fd_handler_del).

Warning
  buf_func is meant for internal use only and should be avoided.

The return value of buf_func has a different meaning, when it returns ECORE_CALLBACK_CANCEL, it indicates that func shouldn't be called, and when it returns ECORE_CALLBACK_RENEW it indicates func should be called. The return value of buf_func will not cause the FD handler to be deleted.

buf_func is called during event loop handling to check if data that has been read from the file descriptor is in a buffer and is available to read. Some systems, notably xlib, handle their own buffering, and would otherwise not work with select(). These systems should use a buf_func. This is a most annoying hack, only ecore_x uses it, so refer to that for an example.

Warning
  This function should not be used for monitoring "normal" files, like text files.

Examples
  ecore_con_client_example.c, ecore_evas_basics_example.c, ecore_exe_example_child.c, ecore_fd_handler_example.c, and ecore_fd_handler_gnutls_example.c.

References EINA_FALSE, EINA_MAIN_LOOP_CHECK_RETURN_VAL, and EINA_TRUE.

Referenced by ecore_drm_device_open(), ecore_fb_input_device_listen(), ecore_pipe_full_add(), ecore_pipe_thaw(), ecore_wl2_display_create(), and ecore_wl_init().

## ◆ ecore_main_fd_handler_file_add()

Ecore_Fd_Handler * ecore_main_fd_handler_file_add | ( | int | fd,
|  | Ecore_Fd_Handler_Flags | flags,
|  | Ecore_Fd_Cb | func,
|  | const void * | data,
|  | Ecore_Fd_Cb | buf_func,
|  | const void * | buf_data
| ) |  |

Adds a callback for activity on the given file descriptor.

Parameters

  fd | The file descriptor to watch.
  flags | To monitor it for reading use `ECORE_FD_READ`, for writing `ECORE_FD_WRITE`, and for error `ECORE_FD_ERROR`. Values by |(ored).
  func | The callback function.
  data | The data to pass to the callback.
  buf_func | The function to call to check if any data has been buffered and already read from the fd. May be `NULL`.
  buf_data | The data to pass to the `buf_func` function.

Returns
  A fd handler handle on success, `NULL` otherwise.

This function is identical to ecore_main_fd_handler_add, except that it supports regular files.

Warning
  This function should ONLY be called with ECORE_FD_ERROR, otherwise it will call the fd handler constantly.
  Do not use this function unless you know what you are doing.

Since
  1.7

References EINA_MAIN_LOOP_CHECK_RETURN_VAL, and EINA_TRUE.

Referenced by ecore_wl2_offer_receive(), and eeze_mount_tabs_watch().

## ◆ ecore_main_fd_handler_prepare_callback_set()

void ecore_main_fd_handler_prepare_callback_set | ( | Ecore_Fd_Handler * | fd_handler,
|  | Ecore_Fd_Prep_Cb | func,
|  | const void * | data
| ) |  |

Sets the prepare callback with data for a given Ecore_Fd_Handler.

Parameters

  fd_handler | The fd handler
  func | The prep function
  data | The data to pass to the prep function

This function will be called prior to any fd handler's callback function (even the other fd handlers), before entering the main loop select function.

Note
  Once a prepare callback is set for a fd handler, it cannot be changed. You need to delete the fd handler and create a new one, to set another callback.
  You probably don't need this function. It is only necessary for very uncommon cases that need special behavior.

Examples
  ecore_fd_handler_example.c.

References eina_list_append(), eina_list_data_find(), and EINA_MAIN_LOOP_CHECK_RETURN.

Referenced by ecore_wl2_display_create().

## ◆ ecore_main_fd_handler_del()

void * ecore_main_fd_handler_del | ( | Ecore_Fd_Handler * | fd_handler | ) |

Marks an FD handler for deletion.

Parameters

  fd_handler | The FD handler.

Returns
  The data pointer set using ecore_main_fd_handler_add, for fd_handler on success, `NULL` otherwise. This function marks an fd handler to be deleted during an iteration of the main loop. It does NOT close the associated fd!

Warning
  If the underlying fd is already closed ecore may complain if the main loop is using epoll internally, and also in some rare cases this may cause crashes and instability. Remember to delete your fd handlers before the fds they listen to are closed.

Examples
  ecore_fd_handler_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

Referenced by ecore_avahi_del(), eeze_mount_tabs_unwatch(), eeze_udev_watch_del(), and elput_input_shutdown().

## ◆ ecore_main_fd_handler_fd_get()

int ecore_main_fd_handler_fd_get | ( | Ecore_Fd_Handler * | fd_handler | ) |

Retrieves the file descriptor that the given handler is handling.

Parameters

  fd_handler | The given FD handler.

Returns
  The file descriptor the handler is watching.

Examples
  ecore_fd_handler_example.c.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

Referenced by ecore_input_joystick_name_get().

## ◆ ecore_main_fd_handler_active_get()

Eina_Bool ecore_main_fd_handler_active_get | ( | Ecore_Fd_Handler * | fd_handler,
|  | Ecore_Fd_Handler_Flags | flags
| ) |  |

Gets which flags are active on an FD handler.

Parameters

  fd_handler | The given FD handler.
  flags | The flags, `ECORE_FD_READ`, `ECORE_FD_WRITE` or `ECORE_FD_ERROR` to query.

Returns
  `EINA_TRUE` if any of the given flags are active, `EINA_FALSE` otherwise.

Examples
  ecore_fd_handler_example.c.

References ECORE_FD_ERROR, ECORE_FD_READ, ECORE_FD_WRITE, EINA_FALSE, EINA_MAIN_LOOP_CHECK_RETURN_VAL, and EINA_TRUE.

## ◆ ecore_main_fd_handler_active_set()

void ecore_main_fd_handler_active_set | ( | Ecore_Fd_Handler * | fd_handler,
|  | Ecore_Fd_Handler_Flags | flags
| ) |  |

Sets what active streams the given FD handler should be monitoring.

Parameters

  fd_handler | The given FD handler.
  flags | The flags to be watching.

Examples
  ecore_fd_handler_gnutls_example.c.

Referenced by ecore_wl2_display_flush().

## ◆ ecore_main_win32_handler_add()

Ecore_Win32_Handler * ecore_main_win32_handler_add | ( | void * | h,
|  | Ecore_Win32_Handle_Cb | func,
|  | const void * | data
| ) |  |

Creates a Ecore_Win32_Handler object and add it to the win32_handlers list.

Parameters

  h | The win32 handler.
  func | The function to add as a callback.
  data | The data to pass to the callback when it is called.

Examples
  ecore_exe_example_child.c.

## ◆ ecore_main_win32_handler_del()

void * ecore_main_win32_handler_del | ( | Ecore_Win32_Handler * | win32_handler | ) |

Sets Ecore_Win32_Handler object to delete state.

The handler will be deleted in the _ecore_main_win32_handlers_cleanup function.

Parameters

  win32_handler | The Ecore_Win32_Handler object.