Loading...
Searching...
No Matches
Output handler

## Data Structures

struct | ly_out
| Printer output structure specifying the type of data output. More...

## Macros

#define | LY_PRINT_SHRINK 0x02
| Common value for data as well as schema printers to avoid formatting indentations and new lines.

## Typedefs

typedef enum LY_OUT_TYPE | LY_OUT_TYPE
| Types of the printer's output.
typedef ssize_t(* | ly_write_clb) (void *user_data, const void *buf, size_t count)
| Generic write callback for data printed by libyang.

## Enumerations

enum | LY_OUT_TYPE { LY_OUT_ERROR = -1 , LY_OUT_FD , LY_OUT_FDSTREAM , LY_OUT_FILE , LY_OUT_FILEPATH , LY_OUT_MEMORY , LY_OUT_CALLBACK }
| Types of the printer's output. More...

## Functions

LIBYANG_API_DECL ly_write_clb | ly_out_clb (struct ly_out *out, ly_write_clb writeclb)
| Get or reset callback function associated with a callback printer handler.
LIBYANG_API_DECL void * | ly_out_clb_arg (struct ly_out *out, void *arg)
| Get or reset callback function's argument associated with a callback printer handler.
LIBYANG_API_DECL int | ly_out_fd (struct ly_out *out, int fd)
| Get or reset file descriptor printer handler.
LIBYANG_API_DECL FILE * | ly_out_file (struct ly_out *out, FILE *f)
| Get or reset file stream printer handler.
LIBYANG_API_DECL const char * | ly_out_filepath (struct ly_out *out, const char *filepath)
| Get or change the filepath of the file where the printer prints the data.
LIBYANG_API_DECL void | ly_out_free (struct ly_out *out, void(*clb_arg_destructor)(void *arg), ly_bool destroy)
| Free the printer handler.
LIBYANG_API_DECL char * | ly_out_memory (struct ly_out *out, char **strp, size_t size)
| Get or change memory where the data are dumped.
LIBYANG_API_DECL LY_ERR | ly_out_new_clb (ly_write_clb writeclb, void *user_data, struct ly_out **out)
| Create printer handler using callback printer function.
LIBYANG_API_DECL LY_ERR | ly_out_new_fd (int fd, struct ly_out **out)
| Create printer handler using file descriptor.
LIBYANG_API_DECL LY_ERR | ly_out_new_file (FILE *f, struct ly_out **out)
| Create printer handler using file stream.
LIBYANG_API_DECL LY_ERR | ly_out_new_filepath (const char *filepath, struct ly_out **out)
| Create printer handler file of the given filename.
LIBYANG_API_DECL LY_ERR | ly_out_new_memory (char **strp, size_t size, struct ly_out **out)
| Create printer handler using memory to dump data.
LIBYANG_API_DECL size_t | ly_out_printed (const struct ly_out *out)
| Get the number of printed bytes by the last function.
LIBYANG_API_DECL size_t | ly_out_printed_total (const struct ly_out *out)
| Get the total number of printed bytes of this out structure.
LIBYANG_API_DECL LY_ERR | ly_out_reset (struct ly_out *out)
| Reset the output medium to write from its beginning, so the following printer function will rewrite the current data instead of appending.
LIBYANG_API_DECL LY_OUT_TYPE | ly_out_type (const struct ly_out *out)
| Get output type of the printer handler.
LIBYANG_API_DECL LY_ERR | ly_print (struct ly_out *out, const char *format,...)
| Generic printer of the given format string into the specified output.
LIBYANG_API_DECL void | ly_print_flush (struct ly_out *out)
| Flush the output from any internal buffers and clean any auxiliary data.
LIBYANG_API_DECL LY_ERR | ly_write (struct ly_out *out, const char *buf, size_t len)
| Generic printer of the given string buffer into the specified output.

## Detailed Description

Structures and functions for output handling.

The output abstraction allows users for transparent use of various output kinds.

## Data Structure Documentation

## ly_out

struct ly_out

Printer output structure specifying the type of data output.

## Macro Definition Documentation

## LY_PRINT_SHRINK

#define LY_PRINT_SHRINK 0x02

Common value for data as well as schema printers to avoid formatting indentations and new lines.

Definition at line 100 of file out.h.

## Typedef Documentation

## LY_OUT_TYPE

typedef enum LY_OUT_TYPE LY_OUT_TYPE

Types of the printer's output.

## ly_write_clb

typedef ssize_t(* ly_write_clb) (void *user_data, const void *buf, size_t count)

Generic write callback for data printed by libyang.

Parameters

  [in] | user_data | Optional caller-specific argument.
  [in] | buf | Data to write.
  [in] | count | Number of bytes to write.

Returns
  Number of printed bytes.
  Negative value in case of error.

Definition at line 147 of file out.h.

## Enumeration Type Documentation

## LY_OUT_TYPE

enum LY_OUT_TYPE

Types of the printer's output.

Enumerator
LY_OUT_ERROR | error value to indicate failure of the functions returning LY_OUT_TYPE
LY_OUT_FD | file descriptor printer
LY_OUT_FDSTREAM | internal replacement for LY_OUT_FD in case vdprintf() is not available
LY_OUT_FILE | FILE stream printer
LY_OUT_FILEPATH | filepath printer
LY_OUT_MEMORY | memory printer
LY_OUT_CALLBACK | callback printer

Definition at line 105 of file out.h.

## Function Documentation

## ly_out_clb()

LIBYANG_API_DECL ly_write_clb ly_out_clb | ( | struct ly_out * | out,
|  | ly_write_clb | writeclb
| ) |  |

Get or reset callback function associated with a callback printer handler.

Parameters

  [in] | out | Printer handler.
  [in] | writeclb | Optional argument providing a new printer callback function for the handler. If NULL, only the current printer callback is returned.

Returns
  Previous printer callback.

## ly_out_clb_arg()

LIBYANG_API_DECL void * ly_out_clb_arg | ( | struct ly_out * | out,
|  | void * | arg
| ) |  |

Get or reset callback function's argument associated with a callback printer handler.

Parameters

  [in] | out | Printer handler.
  [in] | arg | caller-specific argument to be passed to the callback function associated with the printer handler. If NULL, only the current file descriptor value is returned.

Returns
  The previous callback argument.

## ly_out_fd()

LIBYANG_API_DECL int ly_out_fd | ( | struct ly_out * | out,
|  | int | fd
| ) |  |

Get or reset file descriptor printer handler.

Parameters

  [in] | out | Printer handler.
  [in] | fd | Optional value of a new file descriptor for the handler. If -1, only the current file descriptor value is returned.

Returns
  Previous value of the file descriptor. Note that caller is responsible for closing the returned file descriptor in case of setting new descriptor `fd`.
  -1 in case of error when setting up the new file descriptor.

## ly_out_file()

LIBYANG_API_DECL FILE * ly_out_file | ( | struct ly_out * | out,
|  | FILE * | f
| ) |  |

Get or reset file stream printer handler.

Parameters

  [in] | out | Printer handler.
  [in] | f | Optional new file stream for the handler. If NULL, only the current file stream is returned.

Returns
  Previous file stream of the handler. Note that caller is responsible for closing the returned stream in case of setting new stream `f`.

## ly_out_filepath()

LIBYANG_API_DECL const char * ly_out_filepath | ( | struct ly_out * | out,
|  | const char * | filepath
| ) |  |

Get or change the filepath of the file where the printer prints the data.

Note that in case of changing the filepath, the current file is closed and a new one is created/opened instead of renaming the previous file. Also note that the previous filepath string is returned only in case of not changing it's value.

Parameters

  [in] | out | Printer handler.
  [in] | filepath | Optional new filepath for the handler. If and only if NULL, the current filepath string is returned.

Returns
  Previous filepath string in case the `filepath` argument is NULL.
  NULL if changing filepath succeeds and ((void *)-1) otherwise.

## ly_out_free()

LIBYANG_API_DECL void ly_out_free | ( | struct ly_out * | out,
|  | void(*)(void *arg) | clb_arg_destructor,
|  | ly_bool | destroy
| ) |  |

Free the printer handler.

Parameters

  [in] | out | Printer handler to free.
  [in] | clb_arg_destructor | Freeing function for printer callback (LY_OUT_CALLBACK) argument.
  [in] | destroy | Flag to free allocated buffer (for LY_OUT_MEMORY) or to close stream/file descriptor (for LY_OUT_FD, LY_OUT_FDSTREAM and LY_OUT_FILE)

## ly_out_memory()

LIBYANG_API_DECL char * ly_out_memory | ( | struct ly_out * | out,
|  | char ** | strp,
|  | size_t | size
| ) |  |

Get or change memory where the data are dumped.

Parameters

  [in] | out | Printer handler.
  [in] | strp | Optional new string pointer to store the resulting data, same rules as in ly_out_new_memory() are applied.
  [in] | size | Size of the buffer provided via `strp`. In case it is 0, the buffer for the printed data is newly allocated even if `strp` points to a pointer to an existing buffer. In case the `strp` is NULL, this parameter is ignored.

Returns
  Previous dumped data. Note that the caller is responsible to free the data in case of changing string pointer `strp`.

## ly_out_new_clb()

LIBYANG_API_DECL LY_ERR ly_out_new_clb | ( | ly_write_clb | writeclb,
|  | void * | user_data,
|  | struct ly_out ** | out
| ) |  |

Create printer handler using callback printer function.

Parameters

  [in] | writeclb | Pointer to the printer callback function writing the data (see write(2)).
  [in] | user_data | Optional caller-specific argument to be passed to the `writeclb` callback.
  [out] | out | Created printer handler supposed to be passed to different ly*_print() functions.

Returns
  LY_SUCCESS in case of success
  LY_EMEM in case allocating the `out` handler fails.

## ly_out_new_fd()

LIBYANG_API_DECL LY_ERR ly_out_new_fd | ( | int | fd,
|  | struct ly_out ** | out
| ) |  |

Create printer handler using file descriptor.

Parameters

  [in] | fd | File descriptor to use.
  [out] | out | Created printer handler supposed to be passed to different ly*_print() functions.

Returns
  LY_SUCCESS in case of success
  LY_ERR value in case of failure.

## ly_out_new_file()

LIBYANG_API_DECL LY_ERR ly_out_new_file | ( | FILE * | f,
|  | struct ly_out ** | out
| ) |  |

Create printer handler using file stream.

Parameters

  [in] | f | File stream to use.
  [out] | out | Created printer handler supposed to be passed to different ly*_print() functions.

Returns
  LY_SUCCESS in case of success
  LY_ERR value in case of failure.

## ly_out_new_filepath()

LIBYANG_API_DECL LY_ERR ly_out_new_filepath | ( | const char * | filepath,
|  | struct ly_out ** | out
| ) |  |

Create printer handler file of the given filename.

Parameters

  [in] | filepath | Path of the file where to write data.
  [out] | out | Created printer handler supposed to be passed to different ly*_print() functions.

Returns
  NULL in case of error.
  Created printer handler supposed to be passed to different ly*_print_*() functions.

## ly_out_new_memory()

LIBYANG_API_DECL LY_ERR ly_out_new_memory | ( | char ** | strp,
|  | size_t | size,
|  | struct ly_out ** | out
| ) |  |

Create printer handler using memory to dump data.

Parameters

  [in] | strp | Pointer to store the resulting data. If it points to a pointer to an allocated buffer and `size` of the buffer is set, the buffer is used (and extended if needed) to store the printed data.
  [in] | size | Size of the buffer provided via `strp`. In case it is 0, the buffer for the printed data is newly allocated even if `strp` points to a pointer to an existing buffer.
  [out] | out | Created printer handler supposed to be passed to different ly*_print() functions.

Returns
  LY_SUCCESS in case of success
  LY_ERR value in case of failure.

## ly_out_printed()

LIBYANG_API_DECL size_t ly_out_printed | ( | const struct ly_out * | out | ) |

Get the number of printed bytes by the last function.

Parameters

  [in] | out | Out structure used.

Returns
  Number of printed bytes.

## ly_out_printed_total()

LIBYANG_API_DECL size_t ly_out_printed_total | ( | const struct ly_out * | out | ) |

Get the total number of printed bytes of this out structure.

Parameters

  [in] | out | Out structure used.

Returns
  Number of printed bytes.

## ly_out_reset()

LIBYANG_API_DECL LY_ERR ly_out_reset | ( | struct ly_out * | out | ) |

Reset the output medium to write from its beginning, so the following printer function will rewrite the current data instead of appending.

Note that in case the underlying output is not seekable (stream referring a pipe/FIFO/socket or the callback output type), nothing actually happens despite the function succeeds. Also note that the medium is not returned to the state it was when the handler was created. For example, file is seeked into the offset zero and truncated, the content from the time it was opened with ly_out_new_file() is not restored.

Parameters

  [in] | out | Printer handler.

Returns
  LY_SUCCESS in case of success
  LY_ESYS in case of failure

## ly_out_type()

LIBYANG_API_DECL LY_OUT_TYPE ly_out_type | ( | const struct ly_out * | out | ) |

Get output type of the printer handler.

Parameters

  [in] | out | Printer handler.

Returns
  Type of the printer's output.

## ly_print()

LIBYANG_API_DECL LY_ERR ly_print | ( | struct ly_out * | out,
|  | const char * | format,
|  |  | ...
| ) |  |

Generic printer of the given format string into the specified output.

Alternatively, ly_write() can be used.

Parameters

  [in] | out | Output specification.
  [in] | format | Format string to be printed.

Returns
  LY_ERR value, get number of the printed bytes using ly_out_printed.

## ly_print_flush()

LIBYANG_API_DECL void ly_print_flush | ( | struct ly_out * | out | ) |

Flush the output from any internal buffers and clean any auxiliary data.

Parameters

  [in] | out | Output specification.

## ly_write()

LIBYANG_API_DECL LY_ERR ly_write | ( | struct ly_out * | out,
|  | const char * | buf,
|  | size_t | len
| ) |  |

Generic printer of the given string buffer into the specified output.

Alternatively, ly_print() can be used.

Parameters

  [in] | out | Output specification.
  [in] | buf | Memory buffer with the data to print.
  [in] | len | Length of the data to print in the `buf`.

Returns
  LY_ERR value, get number of the printed bytes using ly_out_printed.