upipe/ubuf_block.h header reference

Upipe buffer handling for block managers More

• upipe/ubase.h
• upipe/ubuf.h

• struct ubuf * ubuf_block_alloc(struct ubuf_mgr *mgr, int size)
• int ubuf_block_append(struct ubuf *ubuf, struct ubuf *append)
• int ubuf_block_compare(struct ubuf *ubuf, int offset, struct ubuf *ubuf_small)
• struct ubuf * ubuf_block_copy(struct ubuf_mgr *mgr, struct ubuf *ubuf, int skip, int new_size)
• int ubuf_block_delete(struct ubuf *ubuf, int offset, int size)
• int ubuf_block_equal(struct ubuf *ubuf1, struct ubuf *ubuf2)
• int ubuf_block_extract(struct ubuf *ubuf, int offset, int size, uint8_t *buffer)
• int ubuf_block_find(struct ubuf *ubuf, size_t *offset_p, unsigned int nb_octets, ...)
• int ubuf_block_find_va(struct ubuf *ubuf, size_t *offset_p, unsigned int nb_octets, va_list args)
• int ubuf_block_insert(struct ubuf *ubuf, int offset, struct ubuf *insert)
• int ubuf_block_iovec_count(struct ubuf *ubuf, int offset, int size)
• int ubuf_block_iovec_read(struct ubuf *ubuf, int offset, int size, struct iovec *iovecs)
• int ubuf_block_iovec_unmap(struct ubuf *ubuf, int offset, int size, struct iovec *iovecs)
• int ubuf_block_match(struct ubuf *ubuf, const uint8_t *filter, const uint8_t *mask, size_t size)
• int ubuf_block_merge(struct ubuf_mgr *mgr, struct ubuf **ubuf_p, int skip, int new_size)
• const uint8_t * ubuf_block_peek(struct ubuf *ubuf, int offset, int size, uint8_t *buffer)
• int ubuf_block_peek_unmap(struct ubuf *ubuf, int offset, uint8_t *buffer, const uint8_t *read_buffer)
• int ubuf_block_read(struct ubuf *ubuf, int offset, int *size_p, const uint8_t **buffer_p)
• int ubuf_block_resize(struct ubuf *ubuf, int offset, int new_size)
• int ubuf_block_scan(struct ubuf *ubuf, size_t *offset_p, uint8_t word)
• int ubuf_block_size(struct ubuf *ubuf, size_t *size_p)
• int ubuf_block_size_linear(struct ubuf *ubuf, int offset, size_t *size_p)
• struct ubuf * ubuf_block_splice(struct ubuf *ubuf, int offset, int size)
• int ubuf_block_truncate(struct ubuf *ubuf, int offset)
• int ubuf_block_unmap(struct ubuf *ubuf, int offset)
• int ubuf_block_write(struct ubuf *ubuf, int offset, int *size_p, uint8_t **buffer_p)

• UBUF_ALLOC_BLOCK

This file defines the block-specific API to access buffers.

This macro is declared in upipe/ubuf_block.h source file, line 49.

This macro is a simple signature to make sure the ubuf_alloc internal API is used properly.

This macro is declared in upipe/ubuf_block.h source file, line 32.

This function is declared in upipe/ubuf_block.h source file, line 90.

This function returns a new ubuf from a block allocator. This function shall not create a segmented block.

Parameters list:

• mgr: management structure for this ubuf type
• size: size of the buffer

The return value is pointer to ubuf or NULL in case of failure

This function is declared in upipe/ubuf_block.h source file, line 273.

This function appends a new ubuf at the end of a segmented-to-be block ubuf.

Parameters list:

• ubuf: pointer to ubuf
• append: pointer to ubuf to be appended; it must no longer be used afterwards as it becomes included in the segmented ubuf

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 832.

This function compares the content of a block ubuf in a larger ubuf.

Parameters list:

• ubuf: pointer to large ubuf
• offset: supposed offset of the small ubuf in the large ubuf
• ubuf_small: pointer to small ubuf

The return value is UBASE_ERR_NONE if the small ubuf matches the larger ubuf

This function is declared in upipe/ubuf_block.h source file, line 763.

This function copies part of a ubuf to a newly allocated ubuf.

Parameters list:

• mgr: management structure for this ubuf type
• ubuf: pointer to ubuf to copy
• skip: number of octets to skip at the beginning of the buffer (if < 0, extend buffer upwards)
• size: size of the buffer space wanted, in octets, or -1 for the end of the block

The return value is pointer to newly allocated ubuf or NULL in case of error

This function is declared in upipe/ubuf_block.h source file, line 364.

This function deletes part of a ubuf. The ubuf may become segmented afterwards.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset at which to delete data
• size: number of octets to delete

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 871.

This function compares whether two ubufs are identical.

Parameters list:

• ubuf1: pointer to first ubuf
• ubuf2: pointer to second ubuf

The return value is UBASE_ERR_NONE if the two ubufs are identical

This function is declared in upipe/ubuf_block.h source file, line 611.

This function extracts a ubuf to an arbitrary memory space.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• size: size of the buffer space wanted, in octets, or -1 for the end of the block
• buffer: pointer to buffer space of at least size octets

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 1009.

This function finds a multi-octet word in a block ubuf.

Parameters list:

• ubuf: pointer to ubuf
• offset_p: start offset (in octets), written with the offset of the first wanted word, or first candidate if there aren't enough octets in the ubuf, or the total size of the ubuf if none was found
• nb_octets: number of octets composing the word, followed by a list of octets composing the word, in big-endian ordering

The return value is UBASE_ERR_NONE if the word was found

This function is declared in upipe/ubuf_block.h source file, line 962.

This function finds a multi-octet word in a block ubuf.

Parameters list:

• ubuf: pointer to ubuf
• offset_p: start offset (in octets), written with the offset of the first wanted word, or first candidate if there aren't enough octets in the ubuf, or the total size of the ubuf if none was found
• nb_octets: number of octets composing the word
• args: list of octets composing the word, in big-endian ordering

The return value is UBASE_ERR_NONE if the word was found

This function is declared in upipe/ubuf_block.h source file, line 333.

This function inserts a new ubuf inside a segmented-to-be block ubuf, at the given position.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset at which to insert the given ubuf.
• insert: pointer to ubuf to be inserted at the given offset; it must no longer be used afterwards as it becomes included in the segmented ubuf

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 638.

This function returns the number of iovec needed to send part of a ubuf.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• size: size of the buffer space wanted, in octets, or -1 for the end of the block

The return value is the number of iovec needed, or -1 in case of error

This function is declared in upipe/ubuf_block.h source file, line 671.

This function maps the requested part of a ubuf to the number of iovec given by ubuf_block_iovec_count.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• size: size of the buffer space wanted, in octets, or -1 for the end of the block
• iovecs: iovec structures array

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 706.

This function unmaps the parts of a ubuf previsouly mapped by ubuf_block_iovec_read.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• size: size of the buffer space wanted, in octets, or -1 for the end of the block
• iovec: iovec structures array

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 892.

This function checks if the beginning of a block ubuf matches a filter with a given mask.

Parameters list:

• ubuf: pointer to ubuf
• filter: wanted content
• mask: mask of the bits to check
• size: size (in octets) of filter and mask

The return value is UBASE_ERR_NONE if the ubuf matches

This function is declared in upipe/ubuf_block.h source file, line 813.

This function merges part of a (possibly segmented) ubuf to a newly allocated (non-segmented) ubuf, and replaces the old ubuf with the new ubuf.

Parameters list:

• mgr: management structure for this ubuf type
• ubuf_p: reference to a pointer to ubuf to replace with a non-segmented block ubuf
• skip: number of octets to skip at the beginning of the buffer (if < 0, extend buffer upwards)
• size: size of the buffer space wanted, in octets, or -1 for the end of the block

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 549.

This function peeks into a ubuf for the given amount of octets, and returns a read-only pointer to the buffer. If the buffer space wanted stretches across two or more segments, it is copied to a (caller-supplied) memory space, and a pointer to it is returned. It returns NULL if the ubuf isn't large enough to provide enough data.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• size: size of the buffer space wanted, in octets, or -1 for the end of the block
• buffer: pointer to buffer space of at least size octets, only used if the requested area stretches across two or more segments

The return value is pointer to buffer space, or NULL in case of error

This function is declared in upipe/ubuf_block.h source file, line 592.

This function unmaps the ubuf that's been peeked into, if necessary.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• buffer: caller-supplied buffer space passed to ubuf_block_peek
• read_buffer: buffer returned by ubuf_block_peek

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 191.

This function returns a read-only pointer to the buffer space. You must call ubuf_block_unmap when you're done with the pointer.

The size parameter must be inited with the desired size, or -1 for up to the end of the buffer. However, if the block is segmented, it may be decreased during execution.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• size_p: pointer to the size of the buffer space wanted, in octets, or -1 for the end of the block, changed during execution for the actual readable size
• buffer_p: reference written with a pointer to buffer space if not NULL

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 459.

This function shrinks a block ubuf.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• new_size: final size of the buffer (if set to -1, keep same buffer end)

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 932.

This function scans for an octet word in a block ubuf.

Parameters list:

• ubuf: pointer to ubuf
• offset_p: start offset (in octets), written with the offset of the first wanted word, or the total size of the ubuf if none was found
• word: word to scan for

The return value is UBASE_ERR_NONE if the word was found

This function is declared in upipe/ubuf_block.h source file, line 101.

This function returns the size of the buffer pointed to by a block ubuf.

Parameters list:

• ubuf: pointer to ubuf
• size_p: reference written with the size of the buffer space if not NULL

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 163.

This function returns the size of the largest linear buffer that can be read at a given offset.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• size_p: reference written with the size of the buffer space if not NULL

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 494.

This function duplicates part of a ubuf.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• size: size of the buffer space wanted, in octets, or -1 for the end of the block
• buffer: pointer to buffer space of at least size octets

The return value is newly allocated ubuf

This function is declared in upipe/ubuf_block.h source file, line 415.

This function truncates a ubuf at a given offset, possibly releasing segments.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset at which to truncate data

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 254.

This function marks the buffer space as being currently unused, and the pointer will be invalid until the next time the ubuf is mapped.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end

The return value is an error code

This function is declared in upipe/ubuf_block.h source file, line 226.

This function returns a writable pointer to the buffer space, if the ubuf is not shared. You must call ubuf_block_unmap when you're done with the pointer.

The size parameter must be inited with the desired size, or -1 for up to the end of the buffer. However, if the block is segmented, it may be decreased during execution.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset of the buffer space wanted in the whole block, in octets, negative values start from the end
• size_p: pointer to the size of the buffer space wanted, in octets, or -1 for the end of the block, changed during execution for the actual
• buffer_p: reference written with a pointer to buffer space if not NULL

The return value is an error code

This struct is for internal use only.

This struct is declared in upipe/ubuf_block.h source file, line 56.

This struct is a common section of block ubuf, allowing to segment data. In an opaque area you would typically store a pointer to shared buffer space. It is mandatory for block managers to include this structure instead of struct ubuf.

This function is for internal use only.

This function is declared in upipe/ubuf_block.h source file, line 736.

This function checks the skip and new_size parameters of a lot of resizing functions, and transforms them.

Parameters list:

• ubuf: pointer to ubuf
• skip_p: reference to number of octets to skip at the beginning of the buffer (if < 0, extend buffer upwards)
• new_size_p: reference to final size of the buffer (if set to -1, keep same buffer end)
• ubuf_size_p: filled in with the total size of the ubuf (may be NULL)

The return value is false in case of error

This function is for internal use only.

This function is declared in upipe/ubuf_block.h source file, line 516.

This function checks the offset and size parameters of a lot of functions, and transforms them into absolute offset and size when needed.

Parameters list:

• ubuf: pointer to ubuf
• offset_p: reference to the offset of the buffer space wanted in the whole block, in octets, negative values start from the end (may not be NULL)
• size_p: reference to the size of the buffer space wanted, in octets, or -1 for the end of the block (may not be NULL)

The return value is an error code

This function is for internal use only.

This function is declared in UBASE_FROM_TO function like macro expansion, line 19 in upipe/ubuf_block.h source file, line 80.

This function returns a pointer to ubuf.

Parameters list:

• sub: pointer to struct ubuf

The return value is pointer to struct ubuf_block

This function is for internal use only.

This function is declared in upipe/ubuf_block.h source file, line 123.

This function returns the ubuf corresponding to the given offset.

Parameters list:

• ubuf: pointer to head ubuf
• offset_p: reference to the offset of the buffer space wanted in the whole chain, in octets, negative values start from the end (may not be NULL), filled in with the offset in the matched ubuf
• size_p: reference to the size of the buffer space wanted, in octets, or -1 for the end of the block (may be NULL)

The return value is corresponding chained ubuf

This function is for internal use only.

This function is declared in upipe/ubuf_block.h source file, line 301.

This function splits a block ubuf into two ubufs at the given offset.

Parameters list:

• ubuf: pointer to ubuf
• offset: offset at which to split

The return value is an error code

This function is for internal use only.

This function is declared in UBASE_FROM_TO function like macro expansion, line 9 in upipe/ubuf_block.h source file, line 80.

This function returns a pointer to ubuf.

Parameters list:

• ubuf_block: pointer to struct ubuf_block

The return value is pointer to struct ubuf