Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
jose_io(3)		    Library Functions Manual		      jose_io(3)

NAME
     jose_io - IO Chaining.

SYNOPSIS
   Data Structures
     struct jose_io_t
	 The interface for chained IO.

   Typedefs
     typedef jose_io_t jose_io_auto_t
	 Defines a jose_io_t which calls jose_io_decref() at end of scope.

   Functions
     jose_io_t * jose_io_incref (jose_io_t *io)
	 Increases the reference count of an IO object.
     void jose_io_decref (jose_io_t *io)
	 Decreases the reference count of an IO object.
     jose_io_t * jose_io_malloc (jose_cfg_t *cfg, void **buf, size_t *len)
	 Creates a new IO object which collects data into a dynamic buffer.
     void * jose_io_malloc_steal (void **buf)
	 Steals the buffer created by the jose_io_malloc() IO object.
     jose_io_t * jose_io_buffer (jose_cfg_t *cfg, void *buf, size_t *len)
	 Creates a new IO object which collects data into a static buffer.
     jose_io_t * jose_io_file (jose_cfg_t *cfg, FILE *file)
	 Creates a new IO object which writes data into a FILE.
     jose_io_t	*  jose_io_multiplex  (jose_cfg_t  *cfg, jose_io_t **nexts, bool
	 all)
	 Creates a new IO object which multiplexes data  into  multiple  IO  ob-
	 jects.

Detailed Description
     IO Chaining.

Typedef Documentation
   typedef jose_io_t jose_io_auto_t
     Defines a jose_io_t which calls jose_io_decref() at end of scope. For exam-
     ple:

     void foo() {
	 uint8_t *buf = NULL;
	 size_t len = 0;
	 jose_io_auto_t *io = jose_io_malloc(NULL, &buf, &len);
	 // jose_io_decref() implicitly called
     }

Function Documentation
   jose_io_t* jose_io_incref (jose_io_t * io)
     Increases	the  reference	count of an IO object. This function always suc-
     ceeds.

     Parameters:
	 io The jose_io_t entity you are using.

     Returns:
	 The value of io (for convenience).

   void jose_io_decref (jose_io_t * io)
     Decreases the reference count of an IO object.  When  the	reference  count
     reaches zero, io->free() is called.

     Parameters:
	 io The jose_io_t entity you are using.

   jose_io_t* jose_io_malloc (jose_cfg_t * cfg, void ** buf, size_t * len)
     Creates  a new IO object which collects data into a dynamic buffer. The dy-
     namic buffer is allocated into the buf pointer you provided and the  length
     of  the  buffer is stored in len. The pointer referenced by buf must remain
     valid for the entire duration of the returned IO object.

     The default behavior is for the IO object to zero and free the buffer  when
     it  is  freed.  This means that, by default, you own the buffer pointer but
     the buffer itself is owned by the IO object. You can,  however,  steal  the
     buffer by setting the buffer pointer to NULL.

     See also:
	 jose_io_malloc_steal()

     Parameters:
	 cfg The configuration context (optional).
	 buf A buffer pointer pointer.
	 len A pointer to the length of the buffer.

     Returns:
	 The new IO object or NULL on error.

   void* jose_io_malloc_steal (void ** buf)
     Steals  the  buffer  created by the jose_io_malloc() IO object. This conve-
     nience function simply returns the value of *buf  and  then  sets	*buf  to
     NULL.

     See also:
	 jose_io_malloc()

     Parameters:
	 buf A pointer to the buffer pointer.

     Returns:
	 The value of *buf before it is set to NULL.

   jose_io_t* jose_io_buffer (jose_cfg_t * cfg, void * buf, size_t * len)
     Creates  a new IO object which collects data into a static buffer. The size
     of buf MUST be specified in the variable pointed to by len.  This	will  be
     the maximum data written. However, after the function returns, the variable
     pointed to by len will contain the current length of data in the buffer.

     Unlike  jose_io_malloc(),	you own the buffer and it is not zeroed or freed
     when the IO object is freed.

     Parameters:
	 cfg The configuration context (optional).
	 buf A buffer pointer.
	 len A pointer to the length of the buffer.

     Returns:
	 The new IO object or NULL on error.

   jose_io_t* jose_io_file (jose_cfg_t * cfg, FILE * file)
     Creates a new IO object which writes data into a FILE. This  function  DOES
     NOT  take	ownership  of  the  FILE.  You are still responsible for calling
     fclose() at the appropriate time.

     Parameters:
	 cfg The configuration context (optional).
	 file The output file which MUST be opened for writing or appending.

     Returns:
	 The new IO object or NULL on error.

   jose_io_t* jose_io_multiplex (jose_cfg_t * cfg, jose_io_t ** nexts, bool all)

     Creates a new IO object which multiplexes data into multiple IO objects. If
     all is true, the success of all nexts is required. Otherwise, all	but  one
     of the nexts can fail before the error is propagated upward.

     Parameters:
	 cfg The configuration context (optional).
	 nexts A NULL-terminated array of IO object pointers.
	 all Whether or not the success of all nexts is required.

     Returns:
	 The new IO object or NULL on error.

Author
     Generated automatically by Doxygen for JosA(C) from the source code.

JosA(C) 			 Tue May 30 2017		      jose_io(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=jose_io&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help