| Elektra 0.11.0

Functions
io.c File Reference

Implementation of I/O functions as defined in kdbio.h. More...

`#include <kdbhelper.h>`
`#include <kdbinvoke.h>`
`#include <kdbio.h>`
`#include <kdbioplugin.h>`
`#include <kdbioprivate.h>`
`#include <kdblogger.h>`
`#include <kdbprivate.h>`
`#include <fcntl.h>`
`#include <stdio.h>`

## Functions
int | elektraIoContract (KeySet *contract, ElektraIoInterface *ioBinding)
| Creates a contract for use with kdbOpen() that sets up an I/O binding.
ElektraIoInterface * | elektraIoGetBinding (KDB *kdb)
| Get I/O binding for asynchronous I/O operations for KDB instance.
ElektraIoInterface * | elektraIoNewBinding (ElektraIoBindingAddFd *addFd, ElektraIoBindingUpdateFd *updateFd, ElektraIoBindingRemoveFd *removeFd, ElektraIoBindingAddTimer *addTimer, ElektraIoBindingUpdateTimer *updateTimer, ElektraIoBindingRemoveTimer *removeTimer, ElektraIoBindingAddIdle *addIdle, ElektraIoBindingUpdateIdle *updateIdle, ElektraIoBindingRemoveIdle *removeIdle, ElektraIoBindingCleanup *cleanup)
| Create a new I/O binding.
int | elektraIoBindingAddFd (ElektraIoInterface *binding, ElektraIoFdOperation *fdOp)
| Add file descriptor to be watched by I/O binding.
int | elektraIoBindingUpdateFd (ElektraIoFdOperation *fdOp)
| Notify I/O binding about changes to file descriptor watch operation.
int | elektraIoBindingRemoveFd (ElektraIoFdOperation *fdOp)
| Remove file descriptor from I/O binding.
int | elektraIoBindingAddTimer (ElektraIoInterface *binding, ElektraIoTimerOperation *timerOp)
| Add timer to I/O binding.
int | elektraIoBindingUpdateTimer (ElektraIoTimerOperation *timerOp)
| Notifiy I/O binding about changes to timer structure.
int | elektraIoBindingRemoveTimer (ElektraIoTimerOperation *timerOp)
| Remove timer from I/O binding.
int | elektraIoBindingAddIdle (ElektraIoInterface *binding, ElektraIoIdleOperation *idleOp)
| Add idle to I/O binding.
int | elektraIoBindingUpdateIdle (ElektraIoIdleOperation *idleOp)
| Notifiy I/O binding about changes to idle structure.
int | elektraIoBindingRemoveIdle (ElektraIoIdleOperation *idleOp)
| Remove idle from I/O binding.
int | elektraIoBindingCleanup (ElektraIoInterface *binding)
| Free memory used by I/O binding.
void * | elektraIoBindingGetData (ElektraIoInterface *binding)
| Get private data from I/O Binding.
int | elektraIoBindingSetData (ElektraIoInterface *binding, void *data)
| Set private data from I/O Binding.
ElektraIoFdOperation * | elektraIoNewFdOperation (int fd, int flags, int enabled, ElektraIoFdCallback callback, void *privateData)
| Create a new file descriptor watch operation.
ElektraIoTimerOperation * | elektraIoNewTimerOperation (unsigned int interval, int enabled, ElektraIoTimerCallback callback, void *privateData)
| Create a new timer operation.
ElektraIoIdleOperation * | elektraIoNewIdleOperation (int enabled, ElektraIoIdleCallback callback, void *privateData)
| Create a new idle operation.
int | elektraIoFdSetEnabled (ElektraIoFdOperation *fdOp, int enabled)
| Enable or disable file descriptor watch operation.
int | elektraIoFdSetFlags (ElektraIoFdOperation *fdOp, int flags)
| Update flag bitmask of file descriptor watch operation.
int | elektraIoTimerSetEnabled (ElektraIoTimerOperation *timerOp, int enabled)
| Enable or disable timer operation.
int | elektraIoTimerSetInterval (ElektraIoTimerOperation *timerOp, unsigned int interval)
| Update interval of timer operation.
int | elektraIoIdleSetEnabled (ElektraIoIdleOperation *idleOp, int enabled)
| Enable or disable idle operation.
int | elektraIoFdGetFd (ElektraIoFdOperation *fdOp)
| Get file descriptor number from operation.
void * | elektraIoFdGetData (ElektraIoFdOperation *fdOp)
| Get private data from operation.
int | elektraIoFdSetBindingData (ElektraIoFdOperation *fdOp, void *data)
| Set private binding data for operation.
void * | elektraIoFdGetBindingData (ElektraIoFdOperation *fdOp)
| Get private binding data from operation.
ElektraIoInterface * | elektraIoFdGetBinding (ElektraIoFdOperation *fdOp)
| Get binding from operation.
int | elektraIoFdIsEnabled (ElektraIoFdOperation *fdOp)
| Check if file descriptor watch operation is enabled or disabled.
int | elektraIoFdGetFlags (ElektraIoFdOperation *fdOp)
| Get flag bitmask of file descriptor watch operation.
ElektraIoFdCallback | elektraIoFdGetCallback (ElektraIoFdOperation *fdOp)
| Get callback of file descriptor watch operation.
int | elektraIoTimerSetBindingData (ElektraIoTimerOperation *timerOp, void *data)
| Set private binding data for operation.
void * | elektraIoTimerGetBindingData (ElektraIoTimerOperation *timerOp)
| Get private binding data from operation.
ElektraIoInterface * | elektraIoTimerGetBinding (ElektraIoTimerOperation *timerOp)
| Get binding from operation.
void * | elektraIoTimerGetData (ElektraIoTimerOperation *timerOp)
| Get private data from operation.
int | elektraIoTimerIsEnabled (ElektraIoTimerOperation *timerOp)
| Check if timer operation is enabled or disabled.
unsigned int | elektraIoTimerGetInterval (ElektraIoTimerOperation *timerOp)
| Get interval of timer operation.
ElektraIoTimerCallback | elektraIoTimerGetCallback (ElektraIoTimerOperation *timerOp)
| Get callback of timer operation.
int | elektraIoIdleSetBindingData (ElektraIoIdleOperation *idleOp, void *data)
| Set private binding data for operation.
void * | elektraIoIdleGetBindingData (ElektraIoIdleOperation *idleOp)
| Get private binding data from operation.
ElektraIoInterface * | elektraIoIdleGetBinding (ElektraIoIdleOperation *idleOp)
| Get binding from operation.
void * | elektraIoIdleGetData (ElektraIoIdleOperation *idleOp)
| Get private data from operation.
int | elektraIoIdleIsEnabled (ElektraIoIdleOperation *idleOp)
| Check if idle operation is enabled or disabled.
ElektraIoIdleCallback | elektraIoIdleGetCallback (ElektraIoIdleOperation *idleOp)
| Get callback of idle operation.

## Detailed Description

Implementation of I/O functions as defined in kdbio.h.

Copyright
  BSD License (see LICENSE.md or https://www.libelektra.org)

## Function Documentation

## ◆ elektraIoBindingAddFd()

int elektraIoBindingAddFd | ( | ElektraIoInterface * | binding,
|  | ElektraIoFdOperation * | fdOp
| ) |  |

Add file descriptor to be watched by I/O binding.

An operation may only be added to one binding.

Parameters

  binding | I/O binding handle
  fdOp | file descriptor operation handle

Return values

  1 | on success
  0 | on error

## ◆ elektraIoBindingAddIdle()

int elektraIoBindingAddIdle | ( | ElektraIoInterface * | binding,
|  | ElektraIoIdleOperation * | idleOp
| ) |  |

Add idle to I/O binding.

Idle callbacks are executed without negative effects on other IO sources or the application (e.g. next event loop iteration) An operation may only be added to one binding.

Parameters

  binding | I/O binding handle
  idleOp | idle operation handle

Return values

  1 | on success
  0 | on error

## ◆ elektraIoBindingAddTimer()

int elektraIoBindingAddTimer | ( | ElektraIoInterface * | binding,
|  | ElektraIoTimerOperation * | timerOp
| ) |  |

Add timer to I/O binding.

Timeouts callbacks are executed after the initial interval has elapsed and then repeatedly after the interval has elapsed. An operation may only be added to one binding.

Parameters

  binding | I/O binding handle
  timerOp | timer operation handle

Return values

  1 | on success
  0 | on error

## ◆ elektraIoBindingCleanup()

int elektraIoBindingCleanup | ( | ElektraIoInterface * | binding | ) |

Free memory used by I/O binding.

All added operations have to be removed before calling this function.

Parameters

  binding | I/O binding handle

Return values

  1 | on success
  0 | on error

## ◆ elektraIoBindingGetData()

void * elektraIoBindingGetData | ( | ElektraIoInterface * | binding | ) |

Get private data from I/O Binding.

To be used by I/O binding implementations only.

Parameters

  binding | I/O-Binding handle

Returns
  pointer to data or NULL on error

## ◆ elektraIoBindingRemoveFd()

int elektraIoBindingRemoveFd | ( | ElektraIoFdOperation * | fdOp | ) |

Remove file descriptor from I/O binding.

Parameters

  fdOp | file descriptor operation handle

Return values

  1 | on success
  0 | on error

## ◆ elektraIoBindingRemoveIdle()

int elektraIoBindingRemoveIdle | ( | ElektraIoIdleOperation * | idleOp | ) |

Remove idle from I/O binding.

Parameters

  idleOp | idle operation handle

Return values

  1 | on success
  0 | on error

## ◆ elektraIoBindingRemoveTimer()

int elektraIoBindingRemoveTimer | ( | ElektraIoTimerOperation * | timerOp | ) |

Remove timer from I/O binding.

Parameters

  timerOp | timer operation handle

Return values

  1 | on success
  0 | on error

## ◆ elektraIoBindingSetData()

int elektraIoBindingSetData | ( | ElektraIoInterface * | binding,
|  | void * | data
| ) |  |

Set private data from I/O Binding.

To be used by I/O binding implementations only.

Parameters

  binding | I/O binding handle
  data | private data

Return values

  1 | on success
  0 | on error

## ◆ elektraIoBindingUpdateFd()

int elektraIoBindingUpdateFd | ( | ElektraIoFdOperation * | fdOp | ) |

Notify I/O binding about changes to file descriptor watch operation.

Parameters

  fdOp | file descriptor operation handle

Return values

  1 | on success
  0 | on error

## ◆ elektraIoBindingUpdateIdle()

int elektraIoBindingUpdateIdle | ( | ElektraIoIdleOperation * | idleOp | ) |

Notifiy I/O binding about changes to idle structure.

Parameters

  idleOp | idle operation handle

Return values

  1 | on success
  0 | on error

## ◆ elektraIoBindingUpdateTimer()

int elektraIoBindingUpdateTimer | ( | ElektraIoTimerOperation * | timerOp | ) |

Notifiy I/O binding about changes to timer structure.

Parameters

  timerOp | timer operation handle

Return values

  1 | on success
  0 | on error

## ◆ elektraIoContract()

int elektraIoContract | ( | KeySet * | contract,
|  | ElektraIoInterface * | ioBinding
| ) |  |

Creates a contract for use with kdbOpen() that sets up an I/O binding.

When you call kdbOpen() with this contract, the KDB instance will use `ioBinding` as its I/O binding.

Parameters

  contract | The keyset into which the contract is written.
  ioBinding | The ioBinding to use.

Return values

  -1 | if `contract` or `ioBinding` are NULL
  0 | on success

## ◆ elektraIoFdGetBinding()

ElektraIoInterface * elektraIoFdGetBinding | ( | ElektraIoFdOperation * | fdOp | ) |

Get binding from operation.

Parameters

  fdOp | fd operation handle

Returns
  pointer to binding or NULL on error

## ◆ elektraIoFdGetBindingData()

void * elektraIoFdGetBindingData | ( | ElektraIoFdOperation * | fdOp | ) |

Get private binding data from operation.

Parameters

  fdOp | file descriptor operation handle

Returns
  pointer to data or NULL on error

## ◆ elektraIoFdGetCallback()

ElektraIoFdCallback elektraIoFdGetCallback | ( | ElektraIoFdOperation * | fdOp | ) |

Get callback of file descriptor watch operation.

Parameters

  fdOp | file descriptor operation handle

Returns
  callback

## ◆ elektraIoFdGetData()

void * elektraIoFdGetData | ( | ElektraIoFdOperation * | fdOp | ) |

Get private data from operation.

Parameters

  fdOp | file descriptor operation handle

Returns
  pointer to data or NULL on error

## ◆ elektraIoFdGetFd()

int elektraIoFdGetFd | ( | ElektraIoFdOperation * | fdOp | ) |

Get file descriptor number from operation.

Parameters

  fdOp | file descriptor operation handle

Returns
  file descriptor number or 0 on error

## ◆ elektraIoFdGetFlags()

int elektraIoFdGetFlags | ( | ElektraIoFdOperation * | fdOp | ) |

Get flag bitmask of file descriptor watch operation.

Parameters

  fdOp | file descriptor operation handle

Returns
  watch flag bitmask (see ElektraIoFdFlags).

## ◆ elektraIoFdIsEnabled()

int elektraIoFdIsEnabled | ( | ElektraIoFdOperation * | fdOp | ) |

Check if file descriptor watch operation is enabled or disabled.

Parameters

  fdOp | file descriptor operation handle

Return values

  0 | if disabled
  1 | if enabled

## ◆ elektraIoFdSetBindingData()

int elektraIoFdSetBindingData | ( | ElektraIoFdOperation * | fdOp,
|  | void * | data
| ) |  |

Set private binding data for operation.

Parameters

  fdOp | file descriptor operation handle
  data | pointer to data

Return values

  1 | on success
  0 | on error

## ◆ elektraIoFdSetEnabled()

int elektraIoFdSetEnabled | ( | ElektraIoFdOperation * | fdOp,
|  | int | enabled
| ) |  |

Enable or disable file descriptor watch operation.

Parameters

  fdOp | file descriptor operation handle
  enabled | 0 to disabled, any other value for enabled

Return values

  1 | on success
  0 | on error

## ◆ elektraIoFdSetFlags()

int elektraIoFdSetFlags | ( | ElektraIoFdOperation * | fdOp,
|  | int | flags
| ) |  |

Update flag bitmask of file descriptor watch operation.

Parameters

  fdOp | file descriptor operation handle
  flags | watch flag bitmask (see ElektraIoFdFlags).

Return values

  1 | on success
  0 | on error

## ◆ elektraIoGetBinding()

ElektraIoInterface * elektraIoGetBinding | ( | KDB * | kdb | ) |

Get I/O binding for asynchronous I/O operations for KDB instance.

Returns NULL if no I/O binding was set.

Parameters

  kdb | KDB instance

Returns
  I/O binding or NULL

## ◆ elektraIoIdleGetBinding()

ElektraIoInterface * elektraIoIdleGetBinding | ( | ElektraIoIdleOperation * | idleOp | ) |

Get binding from operation.

Parameters

  idleOp | idle operation handle

Returns
  pointer to binding or NULL on error

## ◆ elektraIoIdleGetBindingData()

void * elektraIoIdleGetBindingData | ( | ElektraIoIdleOperation * | idleOp | ) |

Get private binding data from operation.

Parameters

  idleOp | idle operation handle

Returns
  pointer to data or NULL on error

## ◆ elektraIoIdleGetCallback()

ElektraIoIdleCallback elektraIoIdleGetCallback | ( | ElektraIoIdleOperation * | idleOp | ) |

Get callback of idle operation.

Parameters

  idleOp | idle operation handle

Returns
  callback

## ◆ elektraIoIdleGetData()

void * elektraIoIdleGetData | ( | ElektraIoIdleOperation * | idleOp | ) |

Get private data from operation.

Parameters

  idleOp | idle operation handle

Returns
  pointer to data or NULL on error

## ◆ elektraIoIdleIsEnabled()

int elektraIoIdleIsEnabled | ( | ElektraIoIdleOperation * | idleOp | ) |

Check if idle operation is enabled or disabled.

Parameters

  idleOp | idle operation handle

Return values

  0 | if disabled
  1 | if enabled

## ◆ elektraIoIdleSetBindingData()

int elektraIoIdleSetBindingData | ( | ElektraIoIdleOperation * | idleOp,
|  | void * | data
| ) |  |

Set private binding data for operation.

Parameters

  idleOp | idle operation handle
  data | pointer to data

Return values

  1 | on success
  0 | on error

## ◆ elektraIoIdleSetEnabled()

int elektraIoIdleSetEnabled | ( | ElektraIoIdleOperation * | idleOp,
|  | int | enabled
| ) |  |

Enable or disable idle operation.

Parameters

  idleOp | idle operation handle
  enabled | 0 to disabled, any other value for enabled

Return values

  1 | on success
  0 | on error

## ◆ elektraIoNewBinding()

ElektraIoInterface * elektraIoNewBinding | ( | ElektraIoBindingAddFd * | addFd,
|  | ElektraIoBindingUpdateFd * | updateFd,
|  | ElektraIoBindingRemoveFd * | removeFd,
|  | ElektraIoBindingAddTimer * | addTimer,
|  | ElektraIoBindingUpdateTimer * | updateTimer,
|  | ElektraIoBindingRemoveTimer * | removeTimer,
|  | ElektraIoBindingAddIdle * | addIdle,
|  | ElektraIoBindingUpdateIdle * | updateIdle,
|  | ElektraIoBindingRemoveIdle * | removeIdle,
|  | ElektraIoBindingCleanup * | cleanup
| ) |  |

Create a new I/O binding.

Make sure to free returned data in ElektraIoBindingCleanup.

Parameters

  addFd | function for adding a file descriptor watch operation
  updateFd | function for updating a file descriptor operation
  removeFd | function for removing a file descriptor operation
  addTimer | function for adding a timer operation
  updateTimer | function for updateing a timer operation
  removeTimer | function for removing a timer operation
  addIdle | function for adding an idle operation
  updateIdle | function for updating an idle operation
  removeIdle | function for removing an idle operation
  cleanup | function for cleaning up binding data

Returns
  newly created binding

## ◆ elektraIoNewFdOperation()

ElektraIoFdOperation * elektraIoNewFdOperation | ( | int | fd,
|  | int | flags,
|  | int | enabled,
|  | ElektraIoFdCallback | callback,
|  | void * | data
| ) |  |

Create a new file descriptor watch operation.

Free returned data after use.

Parameters

  fd | file descriptor number
  flags | watch flag bitmask (see ElektraIoFdFlags). Select on which file descriptor state changes the callback should be invoked
  enabled | 0 to disabled, any other value for enabled
  callback | Called when file descriptor state has changes
  data | Custom private data

Returns
  file descriptor operation handle

## ◆ elektraIoNewIdleOperation()

ElektraIoIdleOperation * elektraIoNewIdleOperation | ( | int | enabled,
|  | ElektraIoIdleCallback | callback,
|  | void * | data
| ) |  |

Create a new idle operation.

Free returned data after use.

Parameters

  enabled | 0 to disable, any other value for enabled
  callback | Called when file descriptor state has changes
  data | Custom private data

Returns
  idle operation handle

## ◆ elektraIoNewTimerOperation()

ElektraIoTimerOperation * elektraIoNewTimerOperation | ( | unsigned int | interval,
|  | int | enabled,
|  | ElektraIoTimerCallback | callback,
|  | void * | data
| ) |  |

Create a new timer operation.

Free returned data after use.

Parameters

  interval | timer interval in milliseconds
  enabled | 0 to disable, any other value for enabled
  callback | Called when file descriptor state has changes
  data | Custom private data

Returns
  timer operation handle

## ◆ elektraIoTimerGetBinding()

ElektraIoInterface * elektraIoTimerGetBinding | ( | ElektraIoTimerOperation * | timerOp | ) |

Get binding from operation.

Parameters

  timerOp | timer operation handle

Returns
  pointer to binding or NULL on error

## ◆ elektraIoTimerGetBindingData()

void * elektraIoTimerGetBindingData | ( | ElektraIoTimerOperation * | timerOp | ) |

Get private binding data from operation.

Parameters

  timerOp | timer operation handle

Returns
  pointer to data or NULL on error

## ◆ elektraIoTimerGetCallback()

ElektraIoTimerCallback elektraIoTimerGetCallback | ( | ElektraIoTimerOperation * | timerOp | ) |

Get callback of timer operation.

Parameters

  timerOp | timer operation handle

Returns
  callback

## ◆ elektraIoTimerGetData()

void * elektraIoTimerGetData | ( | ElektraIoTimerOperation * | timerOp | ) |

Get private data from operation.

Parameters

  timerOp | timer operation handle

Returns
  pointer to data or NULL on error

## ◆ elektraIoTimerGetInterval()

unsigned int elektraIoTimerGetInterval | ( | ElektraIoTimerOperation * | timerOp | ) |

Get interval of timer operation.

Parameters

  timerOp | timer operation handle

Returns
  timer interval in milliseconds, 0 on error

## ◆ elektraIoTimerIsEnabled()

int elektraIoTimerIsEnabled | ( | ElektraIoTimerOperation * | timerOp | ) |

Check if timer operation is enabled or disabled.

Parameters

  timerOp | timer operation handle

Return values

  0 | if disabled
  1 | if enabled

## ◆ elektraIoTimerSetBindingData()

int elektraIoTimerSetBindingData | ( | ElektraIoTimerOperation * | timerOp,
|  | void * | data
| ) |  |

Set private binding data for operation.

Parameters

  timerOp | timer operation handle
  data | pointer to data

Return values

  1 | on success
  0 | on error

## ◆ elektraIoTimerSetEnabled()

int elektraIoTimerSetEnabled | ( | ElektraIoTimerOperation * | timerOp,
|  | int | enabled
| ) |  |

Enable or disable timer operation.

Parameters

  timerOp | timer operation handle
  enabled | 0 to disabled, any other value for enabled

Return values

  1 | on success
  0 | on error

## ◆ elektraIoTimerSetInterval()

int elektraIoTimerSetInterval | ( | ElektraIoTimerOperation * | timerOp,
|  | unsigned int | interval
| ) |  |

Update interval of timer operation.

Parameters

  timerOp | timer operation handle
  interval | timer interval in milliseconds

Return values

  1 | on success
  0 | on error