upipe/ubuf_block.h header reference

Upipe buffer handling for block managers More

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

• struct ubuf * ubuf_block_alloc(struct ubuf_mgr *mgr, int size)
• struct ubuf * ubuf_block_alloc_from_opaque(struct ubuf_mgr *mgr, const uint8_t *p, size_t 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_extract_bits(struct ubuf *ubuf, int offset, int size, struct ubits *bw)
• 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_prepend(struct ubuf *ubuf, int prepend)
• 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)
• struct ubuf * ubuf_block_split(struct ubuf *ubuf, int offset)
• 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 50.

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 94.

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

Parameter 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 929.

This function allocates a new ubuf and copies data from an opaque pointer to it.

Parameter list:

• mgr: management structure for this ubuf type
• p: pointer to opaque data
• size: size of opaque data, in octets

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 278.

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

Parameter 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 957.

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

Parameter 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 860.

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

Parameter 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 372.

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

Parameter 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 996.

This function compares whether two ubufs are identical.

Parameter 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 688.

This function extracts a ubuf to an arbitrary memory space.

Parameter 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 716.

This function extracts a ubuf to an ubits bit stream.

Parameter 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
• bw: ubits structure

The return value is an error code

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

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

Parameter 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 1081.

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

Parameter 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 341.

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

Parameter 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 743.

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

Parameter 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 776.

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

Parameter 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 807.

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

Parameter 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 1017.

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

Parameter 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 910.

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.

Parameter 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 626.

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.

Parameter 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 669.

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

Parameter 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 502.

This function prepends a block ubuf, if possible. This will only work if prepend has been correctly specified at allocation.

Should this fail, ubuf_block_merge may be used to achieve the same goal with an extra buffer copy.

Parameter list:

• ubuf: pointer to ubuf
• prepend: number of octets to prepend

The return value is an error code

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

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.

Parameter 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 468.

This function shrinks a block ubuf.

Parameter 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 1051.

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

Parameter 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 105.

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

Parameter 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 167.

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

Parameter 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 530.

This function duplicates part of a ubuf.

Parameter 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 newly allocated ubuf

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

This function splits a ubuf in two, at the specified offset.

Parameter list:

• ubuf: pointer to ubuf, will be truncated at offset
• offset: offset of the split in the original block, in octets, negative value start from the end

The return value is newly allocated ubuf, starting at offset up to the end of the original ubuf

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

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

Parameter 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 259.

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

Parameter 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 231.

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.

Parameter 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 struct is for internal use only.

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

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 ubuf.

This function is for internal use only.

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

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

Parameter 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 593.

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

Parameter 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 84.

This function returns a pointer to ubuf.

Parameter 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 127.

This function returns the ubuf corresponding to the given offset.

Parameter 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 309.

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

Parameter list:

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

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 84.

This function returns a pointer to ubuf.

Parameter list:

• ubuf_block: pointer to struct ubuf_block

The return value is pointer to struct ubuf