From: Zhihsian Que Date: Tue, 11 Aug 2020 13:18:13 +0800 Subject: fix fails to build with sphinx 3.1 --- docs/old/allocation.rst | 64 +++++++++++++++--------------- docs/old/array.rst | 42 ++++++++++---------- docs/old/basic-types.rst | 2 +- docs/old/bitset.rst | 12 +++--- docs/old/buffer.rst | 62 +++++++++++++++--------------- docs/old/cli.rst | 12 +++--- docs/old/dllist.rst | 44 ++++++++++----------- docs/old/errors.rst | 16 ++++---- docs/old/files.rst | 94 ++++++++++++++++++++++----------------------- docs/old/gc.rst | 16 ++++---- docs/old/hash-table.rst | 62 +++++++++++++++--------------- docs/old/hash-values.rst | 6 +-- docs/old/int128.rst | 6 +-- docs/old/managed-buffer.rst | 20 +++++----- docs/old/mempool.rst | 20 +++++----- docs/old/net-addresses.rst | 32 +++++++-------- docs/old/process.rst | 50 ++++++++++++------------ docs/old/ring-buffer.rst | 18 ++++----- docs/old/slice.rst | 50 ++++++++++++------------ docs/old/stream.rst | 24 ++++++------ docs/old/subprocess.rst | 34 ++++++++-------- docs/old/threads.rst | 46 +++++++++++----------- docs/old/timestamps.rst | 16 ++++---- docs/old/unique-ids.rst | 4 +- docs/old/versions.rst | 4 +- 25 files changed, 378 insertions(+), 378 deletions(-) diff --git a/docs/old/allocation.rst b/docs/old/allocation.rst index 211d66e..b778e6e 100644 --- a/docs/old/allocation.rst +++ b/docs/old/allocation.rst @@ -77,10 +77,10 @@ Guaranteed allocation The functions in this section are guaranteed to return a valid newly allocated pointer. If memory allocation fails, the functions will not return. -.. function:: void \*cork_malloc(size_t size) - void \*cork_calloc(size_t count, size_t size) - void \*cork_realloc(void \*ptr, size_t old_size, size_t new_size) - type \*cork_new(TYPE type) +.. function:: void *cork_malloc(size_t size) + void *cork_calloc(size_t count, size_t size) + void *cork_realloc(void *ptr, size_t old_size, size_t new_size) + type *cork_new(TYPE type) The first three functions mimic the standard ``malloc``, ``calloc``, and ``realloc`` functions to allocate (or reallocate) some memory, with the added @@ -114,11 +114,11 @@ Recoverable allocation The functions in this section will return a ``NULL`` pointer if any memory allocation fails, allowing you to recover from the error condition, if possible. -.. function:: void \*cork_xmalloc(size_t size) - void \*cork_xcalloc(size_t count, size_t size) - void \*cork_xrealloc(void \*ptr, size_t old_size, size_t new_size) - void \*cork_xreallocf(void \*ptr, size_t old_size, size_t new_size) - type \*cork_xnew(TYPE type) +.. function:: void *cork_xmalloc(size_t size) + void *cork_xcalloc(size_t count, size_t size) + void *cork_xrealloc(void *ptr, size_t old_size, size_t new_size) + void *cork_xreallocf(void *ptr, size_t old_size, size_t new_size) + type *cork_xnew(TYPE type) The first three functions mimic the standard ``malloc``, ``calloc``, ``realloc`` functions. ``cork_xreallocf`` mimics the common ``reallocf`` @@ -164,9 +164,9 @@ Since this is C, you must free any memory region once you're done with it. You must use one of the functions from this section to free any memory that you created using any of the allocation functions described previously. -.. function:: void cork_free(void \*ptr, size_t size) - void cork_cfree(void \*ptr, size_t count, size_t size) - void cork_delete(TYPE type, void \*ptr) +.. function:: void cork_free(void *ptr, size_t size) + void cork_cfree(void *ptr, size_t count, size_t size) + void cork_delete(TYPE type, void *ptr) Frees a region of memory allocated by one of libcork's allocation functions. @@ -187,10 +187,10 @@ created using any of the allocation functions described previously. Duplicating strings ------------------- -.. function:: const char \*cork_strdup(const char \*str) - const char \*cork_strndup(const char \*str, size_t size) - const char \*cork_xstrdup(const char \*str) - const char \*cork_xstrndup(const char \*str, size_t size) +.. function:: const char *cork_strdup(const char *str) + const char *cork_strndup(const char *str, size_t size) + const char *cork_xstrdup(const char *str) + const char *cork_xstrndup(const char *str, size_t size) These functions mimic the standard ``strdup`` function. They create a copy of an existing C string, allocating exactly as much memory is needed to hold @@ -209,7 +209,7 @@ Duplicating strings ``x`` variant returns a ``NULL`` pointer if the allocation fails; the non-\ ``x`` variant is guaranteed to return a valid pointer to a copied string. -.. function:: void cork_strfree(const char \*str) +.. function:: void cork_strfree(const char *str) Frees *str*, which must have been created using :c:func:`cork_strdup()` or :c:func:`cork_xstrdup()`. @@ -224,7 +224,7 @@ The ``cork_alloc`` type encapsulates a particular memory allocation scheme. To customize how libcork allocates memory, you create a new instance of this type, and then use :c:func:`cork_set_allocator` to register it with libcork. -.. function:: void cork_set_allocator(const struct cork_alloc \*alloc) +.. function:: void cork_set_allocator(const struct cork_alloc *alloc) Override which :ref:`allocator instance ` libcork will use to create and free memory. We will take control of *alloc*; you must not free @@ -237,7 +237,7 @@ and then use :c:func:`cork_set_allocator` to register it with libcork. :c:type:`cork_alloc` parameter or return a :c:type:`cork_alloc` result; these functions are safe to call before calling ``cork_set_allocator``.) -.. var:: const struct cork_alloc \*cork_allocator +.. var:: const struct cork_alloc *cork_allocator The current :ref:`allocator instance ` that libcork will use to create and free memory. @@ -259,7 +259,7 @@ Writing a custom allocator appropriate. -.. function:: struct cork_alloc \*cork_alloc_new_alloc(const struct cork_alloc \*parent) +.. function:: struct cork_alloc *cork_alloc_new_alloc(const struct cork_alloc *parent) ``cork_alloc_new`` creates a new allocator instance. The new instance will itself be allocated using *parent*. You must provide implementations of at @@ -288,7 +288,7 @@ Writing a custom allocator explicitly allocate memory using your new allocator's *parent*. -.. function:: void cork_alloc_set_user_data(struct cork_alloc \*alloc, void \*user_data, cork_free_f free_user_data) +.. function:: void cork_alloc_set_user_data(struct cork_alloc *alloc, void *user_data, cork_free_f free_user_data) Provide a *user_data* pointer, which will be passed unmodified to each allocation method that you register. You can also provide an optional @@ -296,10 +296,10 @@ Writing a custom allocator when the allocator itself is freed. -.. function:: void cork_alloc_set_calloc(struct cork_alloc \*alloc, cork_alloc_calloc_f calloc) - void cork_alloc_set_xcalloc(struct cork_alloc \*alloc, cork_alloc_calloc_f calloc) +.. function:: void cork_alloc_set_calloc(struct cork_alloc *alloc, cork_alloc_calloc_f calloc) + void cork_alloc_set_xcalloc(struct cork_alloc *alloc, cork_alloc_calloc_f calloc) - .. type:: void \*(\*cork_alloc_calloc_f)(const struct cork_alloc \*alloc, size_t count, size_t size) + .. type:: void *(*cork_alloc_calloc_f)(const struct cork_alloc *alloc, size_t count, size_t size) These methods are used to implement the :c:func:`cork_calloc` and :c:func:`cork_xcalloc` functions. Your must allocate and return ``count * @@ -309,10 +309,10 @@ Writing a custom allocator variant should return ``NULL`` if allocation fails. -.. function:: void cork_alloc_set_malloc(struct cork_alloc \*alloc, cork_alloc_malloc_f malloc) - void cork_alloc_set_xmalloc(struct cork_alloc \*alloc, cork_alloc_malloc_f malloc) +.. function:: void cork_alloc_set_malloc(struct cork_alloc *alloc, cork_alloc_malloc_f malloc) + void cork_alloc_set_xmalloc(struct cork_alloc *alloc, cork_alloc_malloc_f malloc) - .. type:: void \*(\*cork_alloc_malloc_f)(const struct cork_alloc \*alloc, size_t size) + .. type:: void *(*cork_alloc_malloc_f)(const struct cork_alloc *alloc, size_t size) These methods are used to implement the :c:func:`cork_malloc` and :c:func:`cork_xmalloc` functions. You must allocate and return *size* @@ -321,10 +321,10 @@ Writing a custom allocator variant should return ``NULL`` if allocation fails. -.. function:: void cork_alloc_set_realloc(struct cork_alloc \*alloc, cork_alloc_realloc_f realloc) - void cork_alloc_set_xrealloc(struct cork_alloc \*alloc, cork_alloc_realloc_f realloc) +.. function:: void cork_alloc_set_realloc(struct cork_alloc *alloc, cork_alloc_realloc_f realloc) + void cork_alloc_set_xrealloc(struct cork_alloc *alloc, cork_alloc_realloc_f realloc) - .. type:: void \*(\*cork_alloc_realloc_f)(const struct cork_alloc \*alloc, void \*ptr, size_t old_size, size_t new_size) + .. type:: void *(*cork_alloc_realloc_f)(const struct cork_alloc *alloc, void *ptr, size_t old_size, size_t new_size) These methods are used to implement the :c:func:`cork_realloc`, :c:func:`cork_xrealloc`, and :c:func:`cork_xreallocf` functions. You @@ -335,9 +335,9 @@ Writing a custom allocator should return ``NULL`` if reallocation fails. -.. function:: void cork_alloc_set_free(struct cork_alloc \*alloc, cork_alloc_free_f free) +.. function:: void cork_alloc_set_free(struct cork_alloc *alloc, cork_alloc_free_f free) - .. type:: void \*(\*cork_alloc_free_f)(const struct cork_alloc \*alloc, void \*ptr, size_t size) + .. type:: void *(*cork_alloc_free_f)(const struct cork_alloc *alloc, void *ptr, size_t size) These methods are used to implement the :c:func:`cork_free`, :c:func:`cork_cfree`, and :c:func:`cork_delete` functions. You must diff --git a/docs/old/array.rst b/docs/old/array.rst index bf765d6..df94793 100644 --- a/docs/old/array.rst +++ b/docs/old/array.rst @@ -20,37 +20,37 @@ necessary to store the elements that you add. A resizable array that contains elements of type *element_type*. -.. function:: void cork_array_init(cork_array(T) \*array) +.. function:: void cork_array_init(cork_array(T) *array) Initializes a new array. You should allocate *array* yourself, presumably on the stack or directly within some other data type. The array will start empty. -.. function:: void cork_array_done(cork_array(T) \*array) +.. function:: void cork_array_done(cork_array(T) *array) Finalizes an array, freeing any storage that was allocated to hold the arrays elements. -.. function:: size_t cork_array_size(cork_array(T) \*array) +.. function:: size_t cork_array_size(cork_array(T) *array) Returns the number of elements in *array*. -.. function:: bool cork_array_is_empty(cork_array(T) \*array) +.. function:: bool cork_array_is_empty(cork_array(T) *array) Returns whether *array* has any elements. -.. function:: void cork_array_void(cork_array(T) \*array) +.. function:: void cork_array_void(cork_array(T) *array) Removes all elements from *array*. -.. function:: T* cork_array_elements(cork_array(T) \*array) +.. function:: T* cork_array_elements(cork_array(T) *array) Returns a pointer to the underlying array of elements in *array*. The elements are guaranteed to be contiguous, just like in a normal C array, but the particular pointer that is returned in **not** guaranteed to be consistent across function calls that modify the contents of the array. -.. function:: T cork_array_at(cork_array(T) \*array, size_t index) +.. function:: T cork_array_at(cork_array(T) *array, size_t index) Returns the element in *array* at the given *index*. Like accessing a normal C array, we don't do any bounds checking. The result is a @@ -60,7 +60,7 @@ necessary to store the elements that you add. cork_array_append(array, 5, err); cork_array_at(array, 0) = 12; -.. function:: void cork_array_append(cork_array(T) \*array, T element) +.. function:: void cork_array_append(cork_array(T) *array, T element) Appends *element* to the end of *array*, reallocating the array's storage if necessary. If you have an ``init`` or ``reset`` callback for @@ -71,18 +71,18 @@ necessary to store the elements that you add. :c:func:`cork_array_append_get` instead, and fill in the allocated element directly. -.. function:: T \*cork_array_append_get(cork_array(T) \*array) +.. function:: T *cork_array_append_get(cork_array(T) *array) Appends a new element to the end of *array*, reallocating the array's storage if necessary, returning a pointer to the new element. -.. function:: int cork_array_ensure_size(cork_array(T) \*array, size_t desired_count) +.. function:: int cork_array_ensure_size(cork_array(T) *array, size_t desired_count) Ensures that *array* has enough allocated space to store *desired_count* elements, reallocating the array's storage if needed. The actual size and existing contents of the array aren't changed. -.. function:: int cork_array_copy(cork_array(T) \*dest, cork_array(T) \*src, cork_copy_f \*copy, void \*user_data) +.. function:: int cork_array_copy(cork_array(T) *dest, cork_array(T) *src, cork_copy_f *copy, void *user_data) Copy elements from *src* to *dest*. If you provide a *copy* function, it will be called on each element to perform the copy. If not, we'll use @@ -93,9 +93,9 @@ necessary to store the elements that you add. for any existing entries (will be overwritten by the copy). We'll call ``init`` or ``reuse`` on each element entry before it's copied. - .. type:: typedef int (\*cork_copy_f)(void \*user_data, void \*dest, const void \*src) + .. type:: typedef int (*cork_copy_f)(void *user_data, void *dest, const void *src) -.. function:: size_t cork_array_element_size(cork_array(T) \*array) +.. function:: size_t cork_array_element_size(cork_array(T) *array) Returns the size of the elements that are stored in *array*. You won't normally need to call this, since you can just use @@ -111,11 +111,11 @@ You can provide callback functions that will be used to automatically initialize and finalize the elements of a resizable array. -.. function:: void cork_array_set_init(cork_array(T) \*array, cork_init_f init) - void cork_array_set_done(cork_array(T) \*array, cork_done_f done) - void cork_array_set_reuse(cork_array(T) \*array, cork_init_f reuse) - void cork_array_set_remove(cork_array(T) \*array, cork_done_f remove) - void cork_array_set_callback_data(cork_array(T) \*array, void \*user_data, cork_free_f free_user_data) +.. function:: void cork_array_set_init(cork_array(T) *array, cork_init_f init) + void cork_array_set_done(cork_array(T) *array, cork_done_f done) + void cork_array_set_reuse(cork_array(T) *array, cork_init_f reuse) + void cork_array_set_remove(cork_array(T) *array, cork_done_f remove) + void cork_array_set_callback_data(cork_array(T) *array, void *user_data, cork_free_f free_user_data) Set one of the callback functions for *array*. There are two pairs of callbacks: ``init`` and ``done``, and ``reuse`` and ``remove``. Within each @@ -143,6 +143,6 @@ and finalize the elements of a resizable array. *free_user_data* function, then we will use that function to free the *user_data* when the array itself is finalized. - .. type:: typedef void (\*cork_init_f)(void \*user_data, void \*value) - typedef void (\*cork_done_f)(void \*user_data, void \*value) - typedef void (\*cork_free_f)(void \*value) + .. type:: typedef void (*cork_init_f)(void *user_data, void *value) + typedef void (*cork_done_f)(void *user_data, void *value) + typedef void (*cork_free_f)(void *value) diff --git a/docs/old/basic-types.rst b/docs/old/basic-types.rst index 4a6fe8f..1daddca 100644 --- a/docs/old/basic-types.rst +++ b/docs/old/basic-types.rst @@ -90,7 +90,7 @@ use the following macro to obtain the pointer to the containing (“subclass”) ``struct``, when given a pointer to the contained (“superclass”) ``struct``: -.. function:: struct_type \*cork_container_of(field_type \*field, TYPE struct_type, FIELD field_name) +.. function:: struct_type *cork_container_of(field_type *field, TYPE struct_type, FIELD field_name) The *struct_type* parameter must be the name of a ``struct`` type, *field_name* must be the name of some field within that diff --git a/docs/old/bitset.rst b/docs/old/bitset.rst index 3cb9b12..2a38391 100644 --- a/docs/old/bitset.rst +++ b/docs/old/bitset.rst @@ -28,12 +28,12 @@ bitset to exhaust the available memory. you the number of bits in total, on or off.) -.. function:: void cork_bitset_init(struct cork_bitset \*set) +.. function:: void cork_bitset_init(struct cork_bitset *set) Initialize a new bitset instance that you've allocated yourself (usually on the stack). All bits will be initialized to ``0``. -.. function:: struct cork_bitset \*cork_bitset_new(size_t bit_count) +.. function:: struct cork_bitset *cork_bitset_new(size_t bit_count) Create a new bitset with enough space to store the given number of bits. All bits will be initialized to ``0``. @@ -45,23 +45,23 @@ bitset to exhaust the available memory. and initialized using :c:func:`cork_bitset_init()`. You must **not** use this function to free a bitset allocated using :c:func:`cork_bitset_new()`. -.. function:: void cork_bitset_free(struct cork_bitset \*set) +.. function:: void cork_bitset_free(struct cork_bitset *set) Finalize and deallocate a bitset, freeing any set content that it contains. This function should only be used for bitsets allocated using :c:func:`cork_bitset_new()`. You must **not** use this function to free a bitset initialized using :c:func:`cork_bitset_init()`. -.. function:: bool cork_bitset_get(struct cork_bitset \*set, size_t index) +.. function:: bool cork_bitset_get(struct cork_bitset *set, size_t index) Return whether the given bit is on or off in *set*. It is your responsibility to ensure that *index* is within the valid range for *set*. -.. function:: void cork_bitset_set(struct cork_bitset \*set, size_t index, bool value) +.. function:: void cork_bitset_set(struct cork_bitset *set, size_t index, bool value) Turn the given bit on or off in *set*. It is your responsibility to ensure that *index* is within the valid range for *set*. -.. function:: void cork_bitset_clear(struct cork_bitset \*set) +.. function:: void cork_bitset_clear(struct cork_bitset *set) Turn off of the bits in *set*. diff --git a/docs/old/buffer.rst b/docs/old/buffer.rst index a149ea5..f79bcd4 100644 --- a/docs/old/buffer.rst +++ b/docs/old/buffer.rst @@ -39,7 +39,7 @@ automatically resizing the underlying buffer when necessary. A resizable binary buffer. - .. member:: void \*buf + .. member:: void *buf The current contents of the buffer. @@ -48,7 +48,7 @@ automatically resizing the underlying buffer when necessary. The current size of the buffer. -.. function:: void cork_buffer_init(struct cork_buffer \*buffer) +.. function:: void cork_buffer_init(struct cork_buffer *buffer) struct cork_buffer CORK_BUFFER_INIT() Initialize a new buffer instance that you've allocated yourself @@ -59,11 +59,11 @@ automatically resizing the underlying buffer when necessary. include space for the content of the buffer; this will be allocated automatically as content is added. -.. function:: struct cork_buffer \*cork_buffer_new(void) +.. function:: struct cork_buffer *cork_buffer_new(void) Allocate and initialize a new buffer instance. -.. function:: void cork_buffer_done(struct cork_buffer \*buffer) +.. function:: void cork_buffer_done(struct cork_buffer *buffer) Finalize a buffer, freeing any content that it contains. This function should only be used for buffers that you allocated yourself, @@ -71,7 +71,7 @@ automatically resizing the underlying buffer when necessary. :c:func:`CORK_BUFFER_INIT()`. You must **not** use this function to free a buffer allocated using :c:func:`cork_buffer_new()`. -.. function:: void cork_buffer_free(struct cork_buffer \*buffer) +.. function:: void cork_buffer_free(struct cork_buffer *buffer) Finalize and deallocate a buffer, freeing any content that it contains. This function should only be used for buffers allocated @@ -79,19 +79,19 @@ automatically resizing the underlying buffer when necessary. function to free a buffer initialized using :c:func:`cork_buffer_init()` or :c:func:`CORK_BUFFER_INIT()`. -.. function:: bool cork_buffer_equal(const struct cork_buffer \*buffer1, const struct cork_buffer \*buffer2) +.. function:: bool cork_buffer_equal(const struct cork_buffer *buffer1, const struct cork_buffer *buffer2) Compare two buffers for equality. -.. function:: void cork_buffer_ensure_size(struct cork_buffer \*buffer, size_t desired_size) +.. function:: void cork_buffer_ensure_size(struct cork_buffer *buffer, size_t desired_size) Ensure that a buffer has allocated enough space to store at least *desired_size* bytes. We won't shrink the size of the buffer's internal storage; if the buffer has already allocated at least *desired_size* bytes, the function acts as a no-op. -.. function:: uint8_t cork_buffer_byte(struct cork_buffer \*buffer, size_t index) - char cork_buffer_char(struct cork_buffer \*buffer, size_t index) +.. function:: uint8_t cork_buffer_byte(struct cork_buffer *buffer, size_t index) + char cork_buffer_char(struct cork_buffer *buffer, size_t index) Return the byte or character at the given index in *buffer*. @@ -113,35 +113,35 @@ any ``cork_buffer`` can be used as a ``NUL``\ -terminated C string is constructed from a data source that doesn't include ``NUL`` terminators. -.. function:: void cork_buffer_clear(struct cork_buffer \*buffer) +.. function:: void cork_buffer_clear(struct cork_buffer *buffer) Clear a buffer. This does not free any storage that the buffer has allocated; this storage will be reused if you add contents back to the buffer. -.. function:: void cork_buffer_truncate(struct cork_buffer \*buffer, size_t length) +.. function:: void cork_buffer_truncate(struct cork_buffer *buffer, size_t length) Truncate a buffer so that contains no more than *length* bytes. If the buffer is already shorter than this, it is not modified. -.. function:: void cork_buffer_copy(struct cork_buffer \*dest, const struct cork_buffer \*src) - void cork_buffer_append_copy(struct cork_buffer \*dest, const struct cork_buffer \*src) +.. function:: void cork_buffer_copy(struct cork_buffer *dest, const struct cork_buffer *src) + void cork_buffer_append_copy(struct cork_buffer *dest, const struct cork_buffer *src) Copy the contents of the *src* buffer into *dest*. The ``_set`` variant clears the buffer first, while the ``_append`` variant adds *src* to whatever content is already there. -.. function:: void cork_buffer_set(struct cork_buffer \*buffer, const void \*src, size_t length) - void cork_buffer_append(struct cork_buffer \*buffer, const void \*src, size_t length) +.. function:: void cork_buffer_set(struct cork_buffer *buffer, const void *src, size_t length) + void cork_buffer_append(struct cork_buffer *buffer, const void *src, size_t length) Copy the contents of *src* into a buffer. The ``_set`` variant clears the buffer first, while the ``_append`` variant adds *src* to whatever content is already there. -.. function:: void cork_buffer_set_string(struct cork_buffer \*buffer, const char \*str) - void cork_buffer_append_string(struct cork_buffer \*buffer, const char \*str) - void cork_buffer_set_literal(struct cork_buffer \*buffer, const char \*str) - void cork_buffer_append_literal(struct cork_buffer \*buffer, const char \*str) +.. function:: void cork_buffer_set_string(struct cork_buffer *buffer, const char *str) + void cork_buffer_append_string(struct cork_buffer *buffer, const char *str) + void cork_buffer_set_literal(struct cork_buffer *buffer, const char *str) + void cork_buffer_append_literal(struct cork_buffer *buffer, const char *str) Copy the contents of *str* (which must be a ``NUL``\ -terminated C string) into a buffer. The ``_set`` variants clears the buffer first, @@ -151,10 +151,10 @@ terminators. at compile time. The ``_string`` variants work with any C string; we use the builtin ``strlen`` function to determine the length of the string. -.. function:: void cork_buffer_printf(struct cork_buffer \*buffer, const char \*format, ...) - void cork_buffer_vprintf(struct cork_buffer \*buffer, const char \*format, va_list args) - void cork_buffer_append_printf(struct cork_buffer \*buffer, const char \*format, ...) - void cork_buffer_append_vprintf(struct cork_buffer \*buffer, const char \*format, va_list args) +.. function:: void cork_buffer_printf(struct cork_buffer *buffer, const char *format, ...) + void cork_buffer_vprintf(struct cork_buffer *buffer, const char *format, va_list args) + void cork_buffer_append_printf(struct cork_buffer *buffer, const char *format, ...) + void cork_buffer_append_vprintf(struct cork_buffer *buffer, const char *format, va_list args) Format data according to a ``printf`` format string, placing the result into a buffer. The ``_append`` variants add the formatted @@ -172,11 +172,11 @@ Pretty-printing We also provide several helper functions for adding pretty-printed content to a ``cork_buffer``. -.. function:: void cork_buffer_append_indent(struct cork_buffer \*buffer, size_t indent) +.. function:: void cork_buffer_append_indent(struct cork_buffer *buffer, size_t indent) Append *indent* spaces to *buffer*. -.. function:: void cork_buffer_append_c_string(struct cork_buffer \*buffer, const char \*str, size_t length) +.. function:: void cork_buffer_append_c_string(struct cork_buffer *buffer, const char *str, size_t length) Append the C string literal representation of *str* to *buffer*. This will include opening and closing double quotes, and any non-printable characters @@ -186,9 +186,9 @@ We also provide several helper functions for adding pretty-printed content to a line, since any embedded newlines will be converted to a ``\n`` escape sequence. -.. function:: void cork_buffer_append_hex_dump(struct cork_buffer \*buffer, size_t indent, const char \*str, size_t length) - void cork_buffer_append_multiline(struct cork_buffer \*buffer, size_t indent, const char \*str, size_t length) - void cork_buffer_append_binary(struct cork_buffer \*buffer, size_t indent, const char \*str, size_t length) +.. function:: void cork_buffer_append_hex_dump(struct cork_buffer *buffer, size_t indent, const char *str, size_t length) + void cork_buffer_append_multiline(struct cork_buffer *buffer, size_t indent, const char *str, size_t length) + void cork_buffer_append_binary(struct cork_buffer *buffer, size_t indent, const char *str, size_t length) Append a pretty-printed representation of *str* to *buffer*. All of these functions can produce multiple lines of output. All lines except for the @@ -222,7 +222,7 @@ payload using a ``cork_buffer``, you can use the functions in this section to produce a corresponding instance of one of libcork's sharable, immutable binary data types. -.. function:: struct cork_managed_buffer \*cork_buffer_to_managed_buffer(struct cork_buffer \*buffer) +.. function:: struct cork_managed_buffer *cork_buffer_to_managed_buffer(struct cork_buffer *buffer) Create a new :ref:`managed buffer ` to manage the contents of a ``cork_buffer`` instance. *buffer* must have been @@ -232,7 +232,7 @@ sharable, immutable binary data types. :c:type:`cork_managed_buffer` instance. You must **not** try to free *buffer* yourself. -.. function:: int cork_buffer_to_slice(struct cork_buffer \*buffer, struct cork_slice \*slice) +.. function:: int cork_buffer_to_slice(struct cork_buffer *buffer, struct cork_slice *slice) Initialize a new :ref:`slice ` to manage the contents of *buffer*. *buffer* must have been allocated on the heap (i.e., using @@ -250,7 +250,7 @@ sharable, immutable binary data types. **must** call :c:func:`cork_slice_finish()` on *slice* when you're done with the slice. -.. function:: struct cork_stream_consumer \*cork_buffer_to_stream_consumer(struct cork_buffer \*buffer) +.. function:: struct cork_stream_consumer *cork_buffer_to_stream_consumer(struct cork_buffer *buffer) Create a new stream consumer that appends any received data into *buffer*. diff --git a/docs/old/cli.rst b/docs/old/cli.rst index 8abef49..f47e1c2 100644 --- a/docs/old/cli.rst +++ b/docs/old/cli.rst @@ -69,7 +69,7 @@ print json``. To define a leaf command, you use the following macro: -.. macro:: cork_leaf_command(const char \*name, const char \*short_description, const char \*usage, const char \*full_help, cork_option_parser parse_options, run) +.. macro:: cork_leaf_command(const char *name, const char *short_description, const char *usage, const char *full_help, cork_option_parser parse_options, run) Returns :c:type:`cork_command` instance that defines a leaf command. *name* is the name of the leaf command; this is the word that the user must type on @@ -101,7 +101,7 @@ To define a leaf command, you use the following macro: function must be an instance of the :c:type:`cork_leaf_command_run` function type: - .. type:: void (\*cork_leaf_command_run)(int argc, char \*\*argv) + .. type:: void (*cork_leaf_command_run)(int argc, char **argv) The *argc* and *argv* parameters will describe any values that appear on the command line after the name of the leaf command. This will *not* @@ -171,7 +171,7 @@ both command sets. To define a command set, you use the following macro: -.. macro:: cork_command_set(const char \*name, const char \*short_description, cork_option_parser parse_options, struct cork_command \*\*subcommands) +.. macro:: cork_command_set(const char *name, const char *short_description, cork_option_parser parse_options, struct cork_command **subcommands) Returns :c:type:`cork_command` instance that defines a command set. *name* is the name of the command set; this is the word that the user must type on @@ -251,7 +251,7 @@ is trivial:: return cork_command_main(&root, argc, argv); } -.. function:: int cork_command_main(struct cork_command \*root, int argc, char \*\*argv) +.. function:: int cork_command_main(struct cork_command *root, int argc, char **argv) Runs a subcommand, as defined by the command-line arguments given by *argc* and *argv*. *root* should define the root command set for the executable. @@ -290,7 +290,7 @@ And all of the following would print out the list of ``set print`` subcommands: You can also print out the help text for a command explicitly by calling the following function: -.. function:: void cork_command_show_help(struct cork_command \*command, const char \*message) +.. function:: void cork_command_show_help(struct cork_command *command, const char *message) Prints out help text for *command*. (If it's a leaf command, this is the full help text. If it's a command set, it's a list of the set's @@ -309,7 +309,7 @@ option parsing library, you just need to conform to the interface described in this section. (Note that the standard ``getopt`` and ``getopt_long`` functions can easily be used in an option parsing function.) -.. type:: int (\*cork_option_parser)(int argc, char \*\*argv) +.. type:: int (*cork_option_parser)(int argc, char **argv) Should parse any command-line options that can appear at this point in the executable's command line. (The options must appear immediately after the diff --git a/docs/old/dllist.rst b/docs/old/dllist.rst index 313cdd1..9534602 100644 --- a/docs/old/dllist.rst +++ b/docs/old/dllist.rst @@ -52,15 +52,15 @@ user`` if you're given a pointer to a :c:type:`cork_dllist_item`. An element of a doubly-linked list. This type will usually be embedded within the type whose instances will be stored in the list. - .. member:: struct cork_dllist_item \*next - struct cork_dllist_item \*prev + .. member:: struct cork_dllist_item *next + struct cork_dllist_item *prev A pointer to the next (or previous) element in the list. If this element marks the end (or beginning) of the list, then *next* (or *prev*) will point to the list's sentinel value. -.. function:: void cork_dllist_init(struct cork_dllist \*list) +.. function:: void cork_dllist_init(struct cork_dllist *list) struct cork_dllist CORK_DLLIST_INIT(SYMBOL name) Initializes a doubly-linked list. The list will initially be empty. @@ -74,14 +74,14 @@ user`` if you're given a pointer to a :c:type:`cork_dllist_item`. Querying a list --------------- -.. function:: size_t cork_dllist_size(const struct cork_dllist \*list) +.. function:: size_t cork_dllist_size(const struct cork_dllist *list) Returns the number of elements in *list*. This operation runs in :math:`O(n)` time. -.. function:: bool cork_dllist_is_empty(struct cork_dllist \*list) +.. function:: bool cork_dllist_is_empty(struct cork_dllist *list) Returns whether *list* is empty. @@ -91,8 +91,8 @@ Querying a list Editing a list -------------- -.. function:: void cork_dllist_add_to_head(struct cork_dllist \*list, struct cork_dllist_item \*element) - void cork_dllist_add_to_tail(struct cork_dllist \*list, struct cork_dllist_item \*element) +.. function:: void cork_dllist_add_to_head(struct cork_dllist *list, struct cork_dllist_item *element) + void cork_dllist_add_to_tail(struct cork_dllist *list, struct cork_dllist_item *element) Adds *element* to *list*. The ``_head`` variant adds the new element to the beginning of the list; the ``_tail`` variant adds it to the end. @@ -111,8 +111,8 @@ Editing a list This operation runs in :math:`O(1)` time. -.. function:: void cork_dllist_add_after(struct cork_dllist_item \*pred, struct cork_dllist_item \*element) - void cork_dllist_add_before(struct cork_dllist_item \*succ, struct cork_dllist_item \*element) +.. function:: void cork_dllist_add_after(struct cork_dllist_item *pred, struct cork_dllist_item *element) + void cork_dllist_add_before(struct cork_dllist_item *succ, struct cork_dllist_item *element) Adds *element* to the same list that *pred* or *succ* belong to. The ``_after`` variant ensures that *element* appears in the list immediately @@ -129,8 +129,8 @@ Editing a list This operation runs in :math:`O(1)` time. -.. function:: void cork_dllist_add_list_to_head(struct cork_dllist \*dest, struct cork_dllist \*src) - void cork_dllist_add_list_to_tail(struct cork_dllist \*dest, struct cork_dllist \*src) +.. function:: void cork_dllist_add_list_to_head(struct cork_dllist *dest, struct cork_dllist *src) + void cork_dllist_add_list_to_tail(struct cork_dllist *dest, struct cork_dllist *src) Moves all of the elements in *src* to *dest*. The ``_head`` variant moves the elements to the beginning of *dest*; the ``_tail`` variant moves them to @@ -139,7 +139,7 @@ Editing a list This operation runs in :math:`O(1)` time. -.. function:: void cork_dllist_remove(struct cork_dllist_item \*element) +.. function:: void cork_dllist_remove(struct cork_dllist_item *element) Removes *element* from the list that it currently belongs to. (Note that you don't have to pass in a pointer to that list.) @@ -160,7 +160,7 @@ a visitor function, which will be applied to each element in the list. (In this case, libcork controls the loop that steps through each element.) -.. function:: int cork_dllist_visit(struct cork_dllist \*list, void \*user_data, cork_dllist_visit_f \*func) +.. function:: int cork_dllist_visit(struct cork_dllist *list, void *user_data, cork_dllist_visit_f *func) Apply a function to each element in *list*. The function is allowed to remove the current element from the list; this will not affect our @@ -174,7 +174,7 @@ element.) always returns ``0``, then you will visit all of the elements in *list*, and we'll return ``0`` from ``cork_dllist_visit``. - .. type:: int cork_dllist_visit_f(void \*user_data, struct cork_dllist_item \*element) + .. type:: int cork_dllist_visit_f(void *user_data, struct cork_dllist_item *element) A function that can be applied to each element in a doubly-linked list. @@ -198,8 +198,8 @@ list as follows (assuming you didn't want to use the built-in The second strategy is to iterate through the elements yourself. -.. macro:: cork_dllist_foreach(struct cork_dllist \*list, struct cork_dllist_item &\*curr, struct cork_dllist_item &\*next, TYPE element_type, TYPE &\*element, FIELD item_field) - cork_dllist_foreach_void(struct cork_dllist \*list, struct cork_dllist_item &\*curr, struct cork_dllist_item &\*next) +.. macro:: cork_dllist_foreach(struct cork_dllist *list, struct cork_dllist_item &*curr, struct cork_dllist_item &*next, TYPE element_type, TYPE &*element, FIELD item_field) + cork_dllist_foreach_void(struct cork_dllist *list, struct cork_dllist_item &*curr, struct cork_dllist_item &*next) Iterate through each element in *list*, executing a statement for each one. You must declare two variables of type ``struct cork_dllist_item *``, and @@ -253,23 +253,23 @@ we wanted to calculuate a sum, however, we'd have to use If the ``foreach`` macros don't provide what you need, you can also iterate through the list manually. -.. function:: struct cork_dllist_item \*cork_dllist_head(struct cork_dllist \*list) - struct cork_dllist_item \*cork_dllist_start(struct cork_dllist \*list) +.. function:: struct cork_dllist_item *cork_dllist_head(struct cork_dllist *list) + struct cork_dllist_item *cork_dllist_start(struct cork_dllist *list) Returns the element at the beginning of *list*. If *list* is empty, then the ``_head`` variant will return ``NULL``, while the ``_start`` variant will return the list's sentinel element. -.. function:: struct cork_dllist_item \*cork_dllist_tail(struct cork_dllist \*list) - struct cork_dllist_item \*cork_dllist_end(struct cork_dllist \*list) +.. function:: struct cork_dllist_item *cork_dllist_tail(struct cork_dllist *list) + struct cork_dllist_item *cork_dllist_end(struct cork_dllist *list) Returns the element at the end of *list*. If *list* is empty, then the ``_tail`` variant will return ``NULL``, while the ``_end`` variant will return the list's sentinel element. -.. function:: bool cork_dllist_is_start(struct cork_dllist \*list, struct cork_dllist_item \*element) - bool cork_dllist_is_end(struct cork_dllist \*list, struct cork_dllist_item \*element) +.. function:: bool cork_dllist_is_start(struct cork_dllist *list, struct cork_dllist_item *element) + bool cork_dllist_is_end(struct cork_dllist *list, struct cork_dllist_item *element) Returns whether *element* marks the start (or end) of *list*. diff --git a/docs/old/errors.rst b/docs/old/errors.rst index 434e203..a937627 100644 --- a/docs/old/errors.rst +++ b/docs/old/errors.rst @@ -79,7 +79,7 @@ functions that you can use to interrogate the current error condition. Returns the error code of the current error condition. If no error has occurred, the result will be :c:macro:`CORK_ERROR_NONE`. -.. function:: const char \*cork_error_message(void) +.. function:: const char *cork_error_message(void) Returns the human-readable string description the current error condition. If no error occurred, the result of this function is @@ -88,9 +88,9 @@ functions that you can use to interrogate the current error condition. You can use the ``cork_error_prefix`` family of functions to add additional context to the beginning of an error message. -.. function:: void cork_error_prefix_printf(const char \*format, ...) - void cork_error_prefix_string(const char \*string) - void cork_error_prefix_vprintf(const char \*format, va_list args) +.. function:: void cork_error_prefix_printf(const char *format, ...) + void cork_error_prefix_string(const char *string) + void cork_error_prefix_vprintf(const char *format, va_list args) Prepends some additional text to the current error condition. @@ -127,9 +127,9 @@ codes if there are other possible results besides a simple “success” and If your function results in an error, you need to fill in the current error condition using the ``cork_error_set`` family of functions: -.. function:: void cork_error_set_printf(cork_error ecode, const char \*format, ...) - void cork_error_set_string(cork_error ecode, const char \*string) - void cork_error_set_vprintf(cork_error ecode, const char \*format, va_list args) +.. function:: void cork_error_set_printf(cork_error ecode, const char *format, ...) + void cork_error_set_string(cork_error ecode, const char *string) + void cork_error_set_vprintf(cork_error ecode, const char *format, va_list args) Fills in the current error condition. The error condition is defined by the error code *ecode*. The human-readable description is constructed @@ -466,7 +466,7 @@ We also provide some helper functions for setting these built-in errors: get the error code from the C library's ``errno`` variable. -.. function:: void cork_abort(const char \*fmt, ...) +.. function:: void cork_abort(const char *fmt, ...) Aborts the current program with an error message given by *fmt* and any additional parameters. diff --git a/docs/old/files.rst b/docs/old/files.rst index b726226..d0497a4 100644 --- a/docs/old/files.rst +++ b/docs/old/files.rst @@ -25,24 +25,24 @@ filesystem. Represents a path in the local filesystem. The path can be relative or absolute. The paths don't have to refer to existing files or directories. -.. function:: struct cork_path \*cork_path_new(const char \*path) - struct cork_path \*cork_path_clone(const struct cork_path \*other) +.. function:: struct cork_path *cork_path_new(const char *path) + struct cork_path *cork_path_clone(const struct cork_path *other) Construct a new path object from the given path string, or as a copy of another path object. -.. function:: void cork_path_free(struct cork_path \*path) +.. function:: void cork_path_free(struct cork_path *path) Free a path object. -.. function:: const char \*cork_path_get(const struct cork_path \*path) +.. function:: const char *cork_path_get(const struct cork_path *path) Return the string content of a path. This is not normalized in any way. The result is guaranteed to be non-``NULL``, but may refer to an empty string. The return value belongs to the path object; you must not modify the contents of the string, nor should you try to free the underlying memory. -.. function:: struct cork_path \*cork_path_absolute(const struct cork_path \*other) +.. function:: struct cork_path *cork_path_absolute(const struct cork_path *other) int cork_path_make_absolute(struct cork_path \path) Convert a relative path into an absolute path. The first variant constructs @@ -52,18 +52,18 @@ filesystem. If there is a problem obtaining the current working directory, these functions will return an error condition. -.. function:: struct cork_path \*cork_path_join(const struct cork_path \*path, const char \*more) - struct cork_path \*cork_path_join_path(const struct cork_path \*path, const struct cork_path \*more) - void \*cork_path_append(struct cork_path \path, const char \*more) - void \*cork_path_append_path(struct cork_path \*path, const struct cork_path \*more) +.. function:: struct cork_path *cork_path_join(const struct cork_path *path, const char *more) + struct cork_path *cork_path_join_path(const struct cork_path *path, const struct cork_path *more) + void *cork_path_append(struct cork_path \path, const char *more) + void *cork_path_append_path(struct cork_path *path, const struct cork_path *more) Concatenate two paths together. The ``join`` variants create a new path object containing the concatenated results. The ``append`` variants overwrite the contents of *path* with the concatenated results. -.. function:: struct cork_path \*cork_path_basename(const struct cork_path \*path) - void \*cork_path_set_basename(struct cork_path \*path) +.. function:: struct cork_path *cork_path_basename(const struct cork_path *path) + void *cork_path_set_basename(struct cork_path *path) Extract the base name of *path*. This is the portion after the final trailing slash. The first variant constructs a new path object to hold the @@ -78,8 +78,8 @@ filesystem. basename("a/b/c/") == "c" cork_path_basename("a/b/c/") == "" -.. function:: struct cork_path \*cork_path_dirname(const struct cork_path \*path) - void \*cork_path_set_dirname(struct cork_path \*path) +.. function:: struct cork_path *cork_path_dirname(const struct cork_path *path) + void *cork_path_set_dirname(struct cork_path *path) Extract the directory name of *path*. This is the portion before the final trailing slash. The first variant constructs a new path object to hold the @@ -102,38 +102,38 @@ Lists of paths A list of paths in the local filesystem. -.. function:: struct cork_path_list \*cork_path_list_new_empty(void) - struct cork_path_list \*cork_path_list_new(const char \*list) +.. function:: struct cork_path_list *cork_path_list_new_empty(void) + struct cork_path_list *cork_path_list_new(const char *list) Create a new list of paths. The first variant creates a list that is initially empty. The second variant takes in a colon-separated list of paths as a single string, and adds each of those paths to the new list. -.. function:: void cork_path_list_free(struct cork_path_list \*list) +.. function:: void cork_path_list_free(struct cork_path_list *list) Free a path list. -.. function:: void cork_path_list_add(struct cork_path_list \*list, struct cork_path \*path) +.. function:: void cork_path_list_add(struct cork_path_list *list, struct cork_path *path) Add *path* to *list*. The list takes control of the path instance; you must not try to free *path* yourself. -.. function:: size_t cork_path_list_size(const struct cork_path_list \*list) +.. function:: size_t cork_path_list_size(const struct cork_path_list *list) Return the number of paths in *list*. -.. function:: const struct cork_path \*cork_path_list_get(const struct cork_path_list \*list, size_t index) +.. function:: const struct cork_path *cork_path_list_get(const struct cork_path_list *list, size_t index) Return the path in *list* at the given *index*. The list still owns the path instance that's returned; you must not try to free it or modify its contents. -.. function:: const char \*cork_path_list_to_string(const struct cork_path_list \*list) +.. function:: const char *cork_path_list_to_string(const struct cork_path_list *list) Return a string containing all of the paths in *list* separated by colons. -.. function:: struct cork_file \*cork_path_list_find_file(const struct cork_path_list \*list, const char \*rel_path) - struct cork_file_list \*cork_path_list_find_files(const struct cork_path_list \*list, const char \*rel_file) +.. function:: struct cork_file *cork_path_list_find_file(const struct cork_path_list *list, const char *rel_path) + struct cork_file_list *cork_path_list_find_files(const struct cork_path_list *list, const char *rel_file) Search for a file in a list of paths. *rel_path* gives the path of the sought-after file, relative to each of the directories in *list*. @@ -149,7 +149,7 @@ Lists of paths Standard paths ============== -.. function:: struct cork_path \*cork_path_home(void) +.. function:: struct cork_path *cork_path_home(void) Return a :c:type:`cork_path` that refers to the current user's home directory. If we can't determine the current user's home directory, we set @@ -158,7 +158,7 @@ Standard paths On POSIX systems, this directory is determined by the ``HOME`` environment variable. -.. function:: struct cork_path_list \*cork_path_config_paths(void) +.. function:: struct cork_path_list *cork_path_config_paths(void) Return a :c:type:`cork_path_list` that includes all of the standard directories that can be used to store configuration files. This includes a @@ -168,7 +168,7 @@ Standard paths On POSIX systems, these directories are defined XDG Base Directory Specification. -.. function:: struct cork_path_list \*cork_path_data_paths(void) +.. function:: struct cork_path_list *cork_path_data_paths(void) Return a :c:type:`cork_path_list` that includes all of the standard directories that can be used to store application data files. This includes @@ -178,7 +178,7 @@ Standard paths On POSIX systems, these directories are defined XDG Base Directory Specification. -.. function:: struct cork_path \*cork_path_user_cache_path(void) +.. function:: struct cork_path *cork_path_user_cache_path(void) Return a :c:type:`cork_path` that refers to a directory that can be used to store cache files created on behalf of the current user. This directory @@ -187,7 +187,7 @@ Standard paths On POSIX systems, these directories are defined XDG Base Directory Specification. -.. function:: struct cork_path \*cork_path_user_runtime_path(void) +.. function:: struct cork_path *cork_path_user_runtime_path(void) Return a :c:type:`cork_path` that refers to a directory that can be used to store small runtime management files on behalf of the current user. @@ -210,8 +210,8 @@ Files Represents a Unix-style file permission set. -.. function:: struct cork_file \*cork_file_new(const char \*path) - struct cork_file \*cork_file_new_from_path(struct cork_path \*path) +.. function:: struct cork_file *cork_file_new(const char *path) + struct cork_file *cork_file_new_from_path(struct cork_path *path) Create a new :c:type:`cork_file` instance to represent the file with the given *path*. The ``_from_path`` variant uses an existing @@ -219,23 +219,23 @@ Files take control of the :c:type`cork_path` instance, so you should not try to free it yourself. -.. function:: void cork_file_free(struct cork_file \*file) +.. function:: void cork_file_free(struct cork_file *file) Free a file instance. -.. function:: const struct cork_path \*cork_file_path(struct cork_file \*file) +.. function:: const struct cork_path *cork_file_path(struct cork_file *file) Return the path of a file. The :c:type:`cork_path` instance belongs to the file; you must not try to modify or free the path instance. -.. function:: int cork_file_exists(struct cork_file \*file, bool \*exists) +.. function:: int cork_file_exists(struct cork_file *file, bool *exists) Check whether a file exists in the filesystem, storing the result in *exists*. The function returns an error condition if we are unable to determine whether the file exists --- for instance, because you do not have permission to look into one of the containing directories. -.. function:: int cork_file_type(struct cork_file \*file, enum cork_file_type \*type) +.. function:: int cork_file_type(struct cork_file *file, enum cork_file_type *type) Return what kind of file the given :c:type:`cork_file` instance refers to. The function returns an error condition if there is an error accessing the @@ -268,7 +268,7 @@ Files We can access *file*, but we do not know what type of file it is. -.. function:: int cork_file_remove(struct cork_file \*file, unsigned int flags) +.. function:: int cork_file_remove(struct cork_file *file, unsigned int flags) Remove *file* from the filesystem. *flags* must be the bitwise OR (``|``) of the following flags. (Use ``0`` if you do not want any of the flags.) @@ -297,7 +297,7 @@ Certain functions can only be applied to a :c:type:`cork_file` instance that refers to a directory. -.. function:: int cork_file_mkdir(struct cork_file \*directory, cork_file_mode mode, unsigned int flags) +.. function:: int cork_file_mkdir(struct cork_file *directory, cork_file_mode mode, unsigned int flags) Create a new directory in the filesystem, with permissions given by *mode*. *flags* must be the bitwise OR (``|``) of the following flags. (Use ``0`` if @@ -318,7 +318,7 @@ refers to a directory. part of the standard ``mkdir -p`` command.) -.. function:: int cork_file_iterate_directory(struct cork_file \*directory, cork_file_directory_iterator iterator, void \*user_data) +.. function:: int cork_file_iterate_directory(struct cork_file *directory, cork_file_directory_iterator iterator, void *user_data) Call *iterator* for each file or subdirectory contained in *directory* (not including the directory's ``.`` and ``..`` entries). This function does not @@ -331,7 +331,7 @@ refers to a directory. *iterator* must be an instance of the following function type: - .. type:: typedef int (\*cork_file_directory_iterator)(struct cork_file \*child, const char \*rel_name, void \*user_data) + .. type:: typedef int (*cork_file_directory_iterator)(struct cork_file *child, const char *rel_name, void *user_data) Called for each child entry in *directory*. *child* will be a file instance referring to the child entry. *rel_name* gives the relative name @@ -345,27 +345,27 @@ Lists of files A list of files in the local filesystem. -.. function:: struct cork_file_list \*cork_file_list_new_empty(void) - struct cork_file_list \*cork_file_list_new(struct cork_path_list \*path_list) +.. function:: struct cork_file_list *cork_file_list_new_empty(void) + struct cork_file_list *cork_file_list_new(struct cork_path_list *path_list) Create a new list of files. The first variant creates a list that is initially empty. The second variant adds a new file instance for each of the paths in *path_list*. -.. function:: void cork_file_list_free(struct cork_file_list \*list) +.. function:: void cork_file_list_free(struct cork_file_list *list) Free a file list. -.. function:: void cork_file_list_add(struct cork_file_list \*list, struct cork_file \*file) +.. function:: void cork_file_list_add(struct cork_file_list *list, struct cork_file *file) Add *file* to *list*. The list takes control of the file instance; you must not try to free *file* yourself. -.. function:: size_t cork_file_list_size(const struct cork_file_list \*list) +.. function:: size_t cork_file_list_size(const struct cork_file_list *list) Return the number of files in *list*. -.. function:: struct cork_file \*cork_file_list_get(const struct cork_file_list \*list, size_t index) +.. function:: struct cork_file *cork_file_list_get(const struct cork_file_list *list, size_t index) Return the file in *list* at the given *index*. The list still owns the file instance that's returned; you must not try to free it. @@ -375,7 +375,7 @@ Lists of files Directory walking ================= -.. function:: int cork_walk_directory(const char \*path, struct cork_dir_walker \*walker) +.. function:: int cork_walk_directory(const char *path, struct cork_dir_walker *walker) Walk through the contents of a directory. *path* can be an absolute or relative path. If it's relative, it will be interpreted relative to the @@ -398,17 +398,17 @@ Directory walking .. type:: struct cork_dir_walker - .. member:: int (\*file)(struct cork_dir_walker \*walker, const char \*full_path, const char \*rel_path, const char \*base_name) + .. member:: int (*file)(struct cork_dir_walker *walker, const char *full_path, const char *rel_path, const char *base_name) Called when a regular file is encountered. - .. member:: int (\*enter_directory)(struct cork_dir_walker \*walker, const char \*full_path, const char \*rel_path, const char \*base_name) + .. member:: int (*enter_directory)(struct cork_dir_walker *walker, const char *full_path, const char *rel_path, const char *base_name) Called when a subdirectory of *path* of encountered. If you don't want to recurse into this directory, return :c:data:`CORK_SKIP_DIRECTORY`. .. macro:: CORK_SKIP_DIRECTORY - .. member:: int (\*leave_directory)(struct cork_dir_walker \*walker, const char \*full_path, const char \*rel_path, const char \*base_name) + .. member:: int (*leave_directory)(struct cork_dir_walker *walker, const char *full_path, const char *rel_path, const char *base_name) Called when a subdirectory has been fully processed. diff --git a/docs/old/gc.rst b/docs/old/gc.rst index a5bff64..af4e694 100644 --- a/docs/old/gc.rst +++ b/docs/old/gc.rst @@ -106,7 +106,7 @@ should increase the object's reference count. When you're done with the pointer, you decrease its reference count. When the reference count drops to ``0``, the garbage collector frees the object. -.. function:: void \*cork_gc_incref(void \*obj) +.. function:: void *cork_gc_incref(void *obj) Increments the reference count of an object *obj* that is managed by the current thread's garbage collector. We always return *obj* as a @@ -114,7 +114,7 @@ drops to ``0``, the garbage collector frees the object. struct my_obj * my_copy_of_obj = cork_gc_incref(obj); -.. function:: void cork_gc_decref(void \*obj) +.. function:: void cork_gc_decref(void *obj) Decrements the reference count of an object *obj* that is managed by the current thread's garbage collector If the reference count drops @@ -255,7 +255,7 @@ Each garbage-collected class must provide an implementation of the .. type:: struct cork_gc_obj_iface - .. member:: void (\*free)(void \*obj) + .. member:: void (*free)(void *obj) This callback is called when a garbage-collected object is about to be freed. You can perform any special cleanup steps in this @@ -267,7 +267,7 @@ Each garbage-collected class must provide an implementation of the If your class doesn't need any additional finalization steps, this entry in the callback interface can be ``NULL``. - .. member:: void (\*recurse)(struct cork_gc \*gc, void \*obj, cork_gc_recurser recurse, void \*ud) + .. member:: void (*recurse)(struct cork_gc *gc, void *obj, cork_gc_recurser recurse, void *ud) This callback is how you inform the garbage collector of your references to other garbage-collected objects. @@ -287,7 +287,7 @@ Each garbage-collected class must provide an implementation of the garbage-collected objects, this entry in the callback interface can be ``NULL``. -.. type:: void (\*cork_gc_recurser)(struct cork_gc \*gc, void \*obj, void \*ud) +.. type:: void (*cork_gc_recurser)(struct cork_gc *gc, void *obj, void *ud) An opaque callback provided by the garbage collector when it calls an object's :c:member:`~cork_gc_obj_iface.recurse` method. @@ -384,14 +384,14 @@ collector hides some additional state in the object's memory region, so you can't allocate the storage using ``malloc`` or :c:func:`cork_new()` directly.) -.. function:: void \*cork_gc_alloc(size_t instance_size, struct cork_gc_obj_iface \*iface) +.. function:: void *cork_gc_alloc(size_t instance_size, struct cork_gc_obj_iface *iface) Allocates a new garbage-collected object that is *instance_size* bytes large. *iface* should be a pointer to a callback interface for the object. If there are any problems allocating the new instance, the program will abort. -.. function:: type \*cork_gc_new_iface(TYPE type, struct cork_gc_obj_iface \*iface) +.. function:: type *cork_gc_new_iface(TYPE type, struct cork_gc_obj_iface *iface) Allocates a new garbage-collected instance of *type*. The size of the memory region to allocate is calculated using the ``sizeof`` @@ -400,7 +400,7 @@ directly.) If there are any problems allocating the new instance, the program will abort. -.. function:: struct name \*cork_gc_new(SYMBOL name) +.. function:: struct name *cork_gc_new(SYMBOL name) Allocates a new garbage-collected instance of :samp:`struct {[name]}`. (Note that you don't pass in the ``struct`` part of the diff --git a/docs/old/hash-table.rst b/docs/old/hash-table.rst index a0586f9..b7b37db 100644 --- a/docs/old/hash-table.rst +++ b/docs/old/hash-table.rst @@ -31,7 +31,7 @@ not be equal.) A hash table. -.. function:: struct cork_hash_table \*cork_hash_table_new(size_t initial_size, unsigned int flags) +.. function:: struct cork_hash_table *cork_hash_table_new(size_t initial_size, unsigned int flags) Creates a new hash table instance. @@ -52,7 +52,7 @@ not be equal.) table. -.. function:: void cork_hash_table_free(struct cork_hash_table \*table) +.. function:: void cork_hash_table_free(struct cork_hash_table *table) Frees a hash table. If you have provided a :c:func:`free_key ` or :c:func:`free_value @@ -64,13 +64,13 @@ not be equal.) The contents of an entry in a hash table. - .. member:: void \*key + .. member:: void *key The key for this entry. There won't be any other entries in the hash table with the same key, as determined by the comparator function that you provide. - .. member:: void \*value + .. member:: void *value The value for this entry. The entry's value is completely opaque to the hash table; we'll never need to compare or interrogate the @@ -88,7 +88,7 @@ Callback functions You can use the callback functions in this section to customize the behavior of a hash table. -.. function:: void cork_hash_table_set_user_data(struct cork_hash_table \*table, void \*user_data, cork_free_f free_user_data) +.. function:: void cork_hash_table_set_user_data(struct cork_hash_table *table, void *user_data, cork_free_f free_user_data) Lets you provide an opaque *user_data* pointer to each of the hash table's callbacks. This lets you provide additional state, other than the hash table @@ -100,12 +100,12 @@ a hash table. Key management ~~~~~~~~~~~~~~ -.. function:: void cork_hash_table_set_hash(struct cork_hash_table \*table, void \*user_data, cork_hash_f hash) +.. function:: void cork_hash_table_set_hash(struct cork_hash_table *table, void *user_data, cork_hash_f hash) The hash table will use the ``hash`` callback to calculate a hash value for each key. - .. type:: cork_hash (\*cork_hash_f)(void \*user_data, const void \*key) + .. type:: cork_hash (*cork_hash_f)(void *user_data, const void *key) .. note:: @@ -117,11 +117,11 @@ Key management distribution (and are fast), and should be safe to use for most key types. -.. function:: void cork_hash_table_set_equals(struct cork_hash_table \*table, void \*user_data, cork_equals_f equals) +.. function:: void cork_hash_table_set_equals(struct cork_hash_table *table, void *user_data, cork_equals_f equals) The hash table will use the ``equals`` callback to compare keys. - .. type:: bool (\*cork_equals_f)(void \*user_data, const void \*key1, const void \*key2) + .. type:: bool (*cork_equals_f)(void *user_data, const void *key1, const void *key2) Built-in key types @@ -130,11 +130,11 @@ Built-in key types We also provide a couple of specialized constructors for common key types, which prevents you from having to duplicate common hashing and comparison functions. -.. function:: struct cork_hash_table \*cork_string_hash_table_new(size_t initial_size, unsigned int flags) +.. function:: struct cork_hash_table *cork_string_hash_table_new(size_t initial_size, unsigned int flags) Create a hash table whose keys will be C strings. -.. function:: struct cork_hash_table \*cork_pointer_hash_table_new(size_t initial_size, unsigned int flags) +.. function:: struct cork_hash_table *cork_pointer_hash_table_new(size_t initial_size, unsigned int flags) Create a hash table where keys should be compared using standard pointer equality. (In other words, keys should only be considered equal if they @@ -144,8 +144,8 @@ prevents you from having to duplicate common hashing and comparison functions. Automatically freeing entries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. function:: void cork_hash_table_set_free_key(struct cork_hash_table \*table, void \*user_data, cork_free_f free_key) - void cork_hash_table_set_free_value(struct cork_hash_table \*table, void \*user_data, cork_free_f free_value) +.. function:: void cork_hash_table_set_free_key(struct cork_hash_table *table, void *user_data, cork_free_f free_key) + void cork_hash_table_set_free_value(struct cork_hash_table *table, void *user_data, cork_free_f free_value) If you provide ``free_key`` and/or ``free_value`` callbacks, then the hash table will take ownership of any keys and values that you add. The hash @@ -178,8 +178,8 @@ particular use case. provide are consistent, just like when you write a :c:func:`hash ` callback. -.. function:: void \*cork_hash_table_get(const struct cork_hash_table \*table, const void \*key) - void \*cork_hash_table_get_hash(const struct cork_hash_table \*table, cork_hash hash, const void \*key) +.. function:: void *cork_hash_table_get(const struct cork_hash_table *table, const void *key) + void *cork_hash_table_get_hash(const struct cork_hash_table *table, cork_hash hash, const void *key) Retrieves the value in *table* with the given *key*. We return ``NULL`` if there's no corresponding entry in the table. This means @@ -188,8 +188,8 @@ particular use case. you need to distinguish those cases, you should use :c:func:`cork_hash_table_get_entry()` instead. -.. function:: struct cork_hash_table_entry \*cork_hash_table_get_entry(const struct cork_hash_table \*table, const void \*key) - struct cork_hash_table_entry \*cork_hash_table_get_entry_hash(const struct cork_hash_table \*table, cork_hash hash, const void \*key) +.. function:: struct cork_hash_table_entry *cork_hash_table_get_entry(const struct cork_hash_table *table, const void *key) + struct cork_hash_table_entry *cork_hash_table_get_entry_hash(const struct cork_hash_table *table, cork_hash hash, const void *key) Retrieves the entry in *table* with the given *key*. We return ``NULL`` if there's no corresponding entry in the table. @@ -201,8 +201,8 @@ particular use case. according to the hasher and comparator functions that you provided for this hash table. -.. function:: struct cork_hash_table_entry \*cork_hash_table_get_or_create(struct cork_hash_table \*table, void \*key, bool \*is_new) - struct cork_hash_table_entry \*cork_hash_table_get_or_create_hash(struct cork_hash_table \*table, cork_hash hash, void \*key, bool \*is_new) +.. function:: struct cork_hash_table_entry *cork_hash_table_get_or_create(struct cork_hash_table *table, void *key, bool *is_new) + struct cork_hash_table_entry *cork_hash_table_get_or_create_hash(struct cork_hash_table *table, cork_hash hash, void *key, bool *is_new) Retrieves the entry in *table* with the given *key*. If there is no entry with the given key, it will be created. (If we can't create @@ -222,8 +222,8 @@ particular use case. if the entry is actually new, especially if there will be a lot successful lookups of existing keys. -.. function:: int cork_hash_table_put(struct cork_hash_table \*table, void \*key, void \*value, bool \*is_new, void \*\*old_key, void \*\*old_value) - int cork_hash_table_put_hash(struct cork_hash_table \*table, cork_hash hash, void \*key, void \*value, bool \*is_new, void \*\*old_key, void \*\*old_value) +.. function:: int cork_hash_table_put(struct cork_hash_table *table, void *key, void *value, bool *is_new, void **old_key, void **old_value) + int cork_hash_table_put_hash(struct cork_hash_table *table, cork_hash hash, void *key, void *value, bool *is_new, void **old_key, void **old_value) Add an entry to a hash table. If there is already an entry with the given key, we will overwrite its key and value with the *key* and @@ -234,7 +234,7 @@ particular use case. value. This can be used, for instance, to finalize an overwritten key or value object. -.. function:: void cork_hash_table_delete_entry(struct cork_hash_table \*table, struct cork_hash_table_entry \*entry) +.. function:: void cork_hash_table_delete_entry(struct cork_hash_table *table, struct cork_hash_table_entry *entry) Removes *entry* from *table*. You must ensure that *entry* refers to a valid, existing entry in the hash table. This function can be more efficient @@ -243,8 +243,8 @@ particular use case. :c:func:`cork_hash_table_get_entry`, since we won't have to search for the entry again. -.. function:: bool cork_hash_table_delete(struct cork_hash_table \*table, const void \*key, void \*\*deleted_key, void \*\*deleted_value) - bool cork_hash_table_delete_hash(struct cork_hash_table \*table, cork_hash hash, const void \*key, void \*\*deleted_key, void \*\*deleted_value) +.. function:: bool cork_hash_table_delete(struct cork_hash_table *table, const void *key, void **deleted_key, void **deleted_value) + bool cork_hash_table_delete_hash(struct cork_hash_table *table, cork_hash hash, const void *key, void **deleted_key, void **deleted_value) Removes the entry with the given *key* from *table*. If there isn't any entry with the given key, we'll return ``false``. If the @@ -263,11 +263,11 @@ particular use case. Other operations ---------------- -.. function:: size_t cork_hash_table_size(const struct cork_hash_table \*table) +.. function:: size_t cork_hash_table_size(const struct cork_hash_table *table) Returns the number of entries in a hash table. -.. function:: void cork_hash_table_clear(struct cork_hash_table \*table) +.. function:: void cork_hash_table_clear(struct cork_hash_table *table) Removes all of the entries in a hash table, without finalizing the hash table itself. @@ -276,7 +276,7 @@ Other operations :c:func:`free_value ` callback for *table*, then we'll automatically free any remaining keys and/or values. -.. function:: int cork_hash_table_ensure_size(struct cork_hash_table \*table, size_t desired_count) +.. function:: int cork_hash_table_ensure_size(struct cork_hash_table *table, size_t desired_count) Ensures that *table* has enough space to efficiently store a certain number of entries. This can be used to reduce (or eliminate) the @@ -307,13 +307,13 @@ With mapping, you write a mapping function that will be applied to each entry in the table. (In this case, libcork controls the loop that steps through each entry.) -.. function:: void cork_hash_table_map(struct cork_hash_table \*table, void \*user_data, cork_hash_table_map_f map) +.. function:: void cork_hash_table_map(struct cork_hash_table *table, void *user_data, cork_hash_table_map_f map) Applies the *map* function to each entry in a hash table. The *map* function's :c:type:`cork_hash_table_map_result` return value can be used to influence the iteration. - .. type:: enum cork_hash_table_map_result (\*cork_hash_table_map_f)(void \*user_data, struct cork_hash_table_entry \*entry) + .. type:: enum cork_hash_table_map_result (*cork_hash_table_map_f)(void *user_data, struct cork_hash_table_entry *entry) The function that will be applied to each entry in a hash table. The function's return value can be used to influence the iteration: @@ -373,11 +373,11 @@ entries in a hash table as you manually iterate through them. table. All of the fields in this type are private. You'll usually allocate this type on the stack. -.. function:: void cork_hash_table_iterator_init(struct cork_hash_table \*table, struct cork_hash_table_iterator \*iterator) +.. function:: void cork_hash_table_iterator_init(struct cork_hash_table *table, struct cork_hash_table_iterator *iterator) Initializes a new iterator for the given hash table. -.. function:: struct cork_hash_table_entry \*cork_hash_table_iterator_next(struct cork_hash_table_iterator \*iterator) +.. function:: struct cork_hash_table_entry *cork_hash_table_iterator_next(struct cork_hash_table_iterator *iterator) Returns the next entry in *iterator*\ 's hash table. If you've already iterated through all of the entries in the table, we'll diff --git a/docs/old/hash-values.rst b/docs/old/hash-values.rst index 00f37d9..19e6c48 100644 --- a/docs/old/hash-values.rst +++ b/docs/old/hash-values.rst @@ -56,7 +56,7 @@ this using the :ref:`cork-hash ` script described below:: .. type:: uint32_t cork_hash -.. function:: cork_hash cork_hash_buffer(cork_hash seed, const void \*src, size_t len) +.. function:: cork_hash cork_hash_buffer(cork_hash seed, const void *src, size_t len) cork_hash cork_hash_variable(cork_hash seed, TYPE val) Incorporate the contents of the given binary buffer or variable into a hash @@ -67,7 +67,7 @@ this using the :ref:`cork-hash ` script described below:: not be consistent across different platforms. The only guarantee is that hash values will be consistest for the duration of the current process. -.. function:: cork_hash cork_stable_hash_buffer(cork_hash seed, const void \*src, size_t len) +.. function:: cork_hash cork_stable_hash_buffer(cork_hash seed, const void *src, size_t len) cork_hash cork_stable_hash_variable(cork_hash seed, TYPE val) Stable versions of :c:func:`cork_hash_buffer` and @@ -78,7 +78,7 @@ this using the :ref:`cork-hash ` script described below:: .. type:: cork_big_hash -.. function:: cork_big_hash cork_big_hash_buffer(cork_big_hash seed, const void \*src, size_t len) +.. function:: cork_big_hash cork_big_hash_buffer(cork_big_hash seed, const void *src, size_t len) Incorporate the contents of the given binary buffer into a "big" hash value. A big hash value has a much larger space of possible hash values (128 bits vs diff --git a/docs/old/int128.rst b/docs/old/int128.rst index 7247216..4779a9c 100644 --- a/docs/old/int128.rst +++ b/docs/old/int128.rst @@ -114,9 +114,9 @@ functions, so you won't incur any function-call overhead when using them. Printing ======== -.. function:: const char \*cork_u128_to_decimal(char \*buf, cork_u128 value) - const char \*cork_u128_to_hex(char \*buf, cork_u128 value) - const char \*cork_u128_to_padded_hex(char \*buf, cork_u128 value) +.. function:: const char *cork_u128_to_decimal(char *buf, cork_u128 value) + const char *cork_u128_to_hex(char *buf, cork_u128 value) + const char *cork_u128_to_padded_hex(char *buf, cork_u128 value) Write the string representation of *value* into *buf*. The ``decimal`` and ``hex`` variants do not include any padding in the result. The diff --git a/docs/old/managed-buffer.rst b/docs/old/managed-buffer.rst index 16ddf75..b134817 100644 --- a/docs/old/managed-buffer.rst +++ b/docs/old/managed-buffer.rst @@ -32,7 +32,7 @@ implies, a slice can refer to a subset of the buffer. class private. Managed buffer implementors should fill in this fields when constructing a new ``cork_managed_buffer`` instance. - .. member:: const void \*buf + .. member:: const void *buf The buffer that this instance manages. @@ -45,25 +45,25 @@ implies, a slice can refer to a subset of the buffer. A reference count for the buffer. If this drops to ``0``, the buffer will be finalized. - .. member:: struct cork_managed_buffer_iface \*iface + .. member:: struct cork_managed_buffer_iface *iface The managed buffer implementation for this instance. -.. function:: struct cork_managed_buffer \*cork_managed_buffer_ref(struct cork_managed_buffer \*buf) +.. function:: struct cork_managed_buffer *cork_managed_buffer_ref(struct cork_managed_buffer *buf) Atomically increase the reference count of a managed buffer. This function is thread-safe. -.. function:: void cork_managed_buffer_unref(struct cork_managed_buffer \*buf) +.. function:: void cork_managed_buffer_unref(struct cork_managed_buffer *buf) Atomically decrease the reference count of a managed buffer. If the reference count falls to ``0``, the instance is freed. This function is thread-safe. -.. function:: int cork_managed_buffer_slice(struct cork_slice \*dest, struct cork_managed_buffer \*buffer, size_t offset, size_t length) - int cork_managed_buffer_slice_offset(struct cork_slice \*dest, struct cork_managed_buffer \*buffer, size_t offset) +.. function:: int cork_managed_buffer_slice(struct cork_slice *dest, struct cork_managed_buffer *buffer, size_t offset, size_t length) + int cork_managed_buffer_slice_offset(struct cork_slice *dest, struct cork_managed_buffer *buffer, size_t offset) Initialize a new slice that refers to a subset of a managed buffer. The *offset* and *length* parameters identify the subset. (For the @@ -82,19 +82,19 @@ implies, a slice can refer to a subset of the buffer. Predefined managed buffer implementations ----------------------------------------- -.. function:: struct cork_managed_buffer \*cork_managed_buffer_new_copy(const void \*buf, size_t size) +.. function:: struct cork_managed_buffer *cork_managed_buffer_new_copy(const void *buf, size_t size) Make a copy of *buf*, and allocate a new managed buffer to manage this copy. The copy will automatically be freed when the managed buffer's reference count drops to ``0``. -.. type:: void (\*cork_managed_buffer_freer)(void \*buf, size_t size) +.. type:: void (*cork_managed_buffer_freer)(void *buf, size_t size) A finalization function for a managed buffer created by :c:func:`cork_managed_buffer_new()`. -.. function:: struct cork_managed_buffer \*cork_managed_buffer_new(const void \*buf, size_t size, cork_managed_buffer_freer free) +.. function:: struct cork_managed_buffer *cork_managed_buffer_new(const void *buf, size_t size, cork_managed_buffer_freer free) Allocate a new managed buffer to manage an existing buffer (*buf*). The existing buffer is *not* copied; the new managed buffer instance @@ -119,7 +119,7 @@ Custom managed buffer implementations The interface of methods that managed buffer implementations must provide. - .. member:: void (\*free)(struct cork_managed_buffer \*self) + .. member:: void (*free)(struct cork_managed_buffer *self) Free the contents of a managed buffer, and the ``cork_managed_buffer`` instance itself. diff --git a/docs/old/mempool.rst b/docs/old/mempool.rst index 85bf112..397adb7 100644 --- a/docs/old/mempool.rst +++ b/docs/old/mempool.rst @@ -35,33 +35,33 @@ Basic interface the same size; this size is provided when you initialize the memory pool. -.. function:: struct cork_mempool \*cork_mempool_new_size(size_t element_size) - struct cork_mempool \*cork_mempool_new(TYPE type) +.. function:: struct cork_mempool *cork_mempool_new_size(size_t element_size) + struct cork_mempool *cork_mempool_new(TYPE type) Allocate a new memory pool. The size of the objects allocated by the memory pool is given either as an explicit *element_size*, or by giving the *type* of the objects. The blocks allocated by the memory pool will be of a default size (currently 4Kb). -.. function:: struct cork_mempool \*cork_mempool_new_size_ex(size_t element_size, size_t block_size) - struct cork_mempool \*cork_mempool_new_ex(TYPE type, size_t block_size) +.. function:: struct cork_mempool *cork_mempool_new_size_ex(size_t element_size, size_t block_size) + struct cork_mempool *cork_mempool_new_ex(TYPE type, size_t block_size) Allocate a new memory pool. The size of the objects allocated by the memory pool is given either as an explicit *element_size*, or by giving the *type* of the objects. The blocks allocated by the memory pool will be *block_size* bytes large. -.. function:: void cork_mempool_free(struct cork_mempool \*mp) +.. function:: void cork_mempool_free(struct cork_mempool *mp) Free a memory pool. You **must** have already freed all of the objects allocated by the pool; if you haven't, then this function will cause the current process to abort. -.. function:: void \*cork_mempool_new_object(struct cork_mempool \*mp) +.. function:: void *cork_mempool_new_object(struct cork_mempool *mp) Allocate a new object from the memory pool. -.. function:: void cork_mempool_free_object(struct cork_mempool \*mp, void \*ptr) +.. function:: void cork_mempool_free_object(struct cork_mempool *mp, void *ptr) Free an object that was allocated from the memory pool. @@ -126,9 +126,9 @@ instance, we might as well try to reuse the memory for the ``scratch_space`` field, as well. To do this, you provide initialization and finalization callbacks: -.. function:: void cork_mempool_set_user_data(struct cork_mempool \*mp, void \*user_data, cork_free_f free_user_data) - void cork_mempool_set_init_object(struct cork_mempool \*mp, cork_init_f init_object) - void cork_mempool_set_done_object(struct cork_mempool \*mp, cork_done_f done_object) +.. function:: void cork_mempool_set_user_data(struct cork_mempool *mp, void *user_data, cork_free_f free_user_data) + void cork_mempool_set_init_object(struct cork_mempool *mp, cork_init_f init_object) + void cork_mempool_set_done_object(struct cork_mempool *mp, cork_done_f done_object) Provide callback functions that will be used to initialize and finalize each object created by the memory pool. diff --git a/docs/old/net-addresses.rst b/docs/old/net-addresses.rst index bea320d..e4ab52c 100644 --- a/docs/old/net-addresses.rst +++ b/docs/old/net-addresses.rst @@ -55,10 +55,10 @@ and the equivalent ``::ffff:0:0/96`` IPv4-mapped IPv6 address.) version. -.. function:: void cork_ipv4_copy(struct cork_ipv4 \*addr, const void \*src) - void cork_ipv6_copy(struct cork_ipv6 \*addr, const void \*src) - void cork_ip_from_ipv4(struct cork_ip \*addr, const void \*src) - void cork_ip_from_ipv6(struct cork_ip \*addr, const void \*src) +.. function:: void cork_ipv4_copy(struct cork_ipv4 *addr, const void *src) + void cork_ipv6_copy(struct cork_ipv6 *addr, const void *src) + void cork_ip_from_ipv4(struct cork_ip *addr, const void *src) + void cork_ip_from_ipv6(struct cork_ip *addr, const void *src) Initializes a :c:type:`cork_ipv4`, :c:type:`cork_ipv6`, or :c:type:`cork_ip` instance from an existing IP address somewhere in @@ -69,9 +69,9 @@ and the equivalent ``::ffff:0:0/96`` IPv4-mapped IPv6 address.) in network-endian order, regardless of the host's endianness.) -.. function:: int cork_ipv4_init(struct cork_ipv4 \*addr, const char \*str) - int cork_ipv6_init(struct cork_ipv6 \*addr, const char \*str) - int cork_ip_init(struct cork_ip \*addr, const char \*str) +.. function:: int cork_ipv4_init(struct cork_ipv4 *addr, const char *str) + int cork_ipv6_init(struct cork_ipv6 *addr, const char *str) + int cork_ip_init(struct cork_ip *addr, const char *str) Initializes a :c:type:`cork_ipv4`, :c:type:`cork_ipv6`, or :c:type:`cork_ip` instance from the string representation of an IP @@ -88,9 +88,9 @@ and the equivalent ``::ffff:0:0/96`` IPv4-mapped IPv6 address.) return ``-1``. -.. function:: bool cork_ipv4_equal(const struct cork_ipv4 \*addr1, const struct cork_ipv4 \*addr2) - bool cork_ipv6_equal(const struct cork_ipv6 \*addr1, const struct cork_ipv6 \*addr2) - bool cork_ip_equal(const struct cork_ip \*addr1, const struct cork_ip \*addr2) +.. function:: bool cork_ipv4_equal(const struct cork_ipv4 *addr1, const struct cork_ipv4 *addr2) + bool cork_ipv6_equal(const struct cork_ipv6 *addr1, const struct cork_ipv6 *addr2) + bool cork_ip_equal(const struct cork_ip *addr1, const struct cork_ip *addr2) Checks two IP addresses for equality. @@ -102,9 +102,9 @@ and the equivalent ``::ffff:0:0/96`` IPv4-mapped IPv6 address.) The maximum length of the string representation of an IPv4, IPv6, or generic IP address, including a ``NUL`` terminator. -.. function:: void cork_ipv4_to_raw_string(const struct cork_ipv4 \*addr, char \*dest) - void cork_ipv6_to_raw_string(const struct cork_ipv6 \*addr, char \*dest) - void cork_ip_to_raw_string(const struct cork_ip \*addr, char \*dest) +.. function:: void cork_ipv4_to_raw_string(const struct cork_ipv4 *addr, char *dest) + void cork_ipv6_to_raw_string(const struct cork_ipv6 *addr, char *dest) + void cork_ip_to_raw_string(const struct cork_ip *addr, char *dest) Fills in *dest* with the string representation of an IPv4, IPv6, or generic IP address. You are responsible for ensuring that *dest* is @@ -119,9 +119,9 @@ and the equivalent ``::ffff:0:0/96`` IPv4-mapped IPv6 address.) cork_ipv4_to_raw_string(&addr, buf); -.. function:: bool cork_ipv4_is_valid_network(const struct cork_ipv4 \*addr, unsigned int cidr_prefix) - bool cork_ipv6_is_valid_network(const struct cork_ipv6 \*addr, unsigned int cidr_prefix) - bool cork_ip_is_valid_network(const struct cork_ipv6 \*addr, unsigned int cidr_prefix) +.. function:: bool cork_ipv4_is_valid_network(const struct cork_ipv4 *addr, unsigned int cidr_prefix) + bool cork_ipv6_is_valid_network(const struct cork_ipv6 *addr, unsigned int cidr_prefix) + bool cork_ip_is_valid_network(const struct cork_ipv6 *addr, unsigned int cidr_prefix) Checks an IP address for alignment with a CIDR block prefix. For example, 10.1.2.4/24 is invalid, but 10.1.2.4/30 is valid. diff --git a/docs/old/process.rst b/docs/old/process.rst index 3bb13ec..c98c421 100644 --- a/docs/old/process.rst +++ b/docs/old/process.rst @@ -20,7 +20,7 @@ Often you will need to perform some cleanup tasks whenever the current process terminates normally. The functions in this section let you do that. .. function:: void cork_cleanup_at_exit(int priority, cork_cleanup_function function) - void cork_cleanup_at_exit_named(const char \*name, int priority, cork_cleanup_function function) + void cork_cleanup_at_exit_named(const char *name, int priority, cork_cleanup_function function) Register a *function* that should be called when the current process terminates. When multiple functions are registered, the order in which they @@ -30,7 +30,7 @@ terminates normally. The functions in this section let you do that. All cleanup functions must conform to the following signature: - .. type:: void (\*cork_cleanup_function)(void) + .. type:: void (*cork_cleanup_function)(void) The ``_named`` variant lets you provide an explicit name for the cleanup function, which currently is only used when printing out debug messages. The @@ -48,21 +48,21 @@ Environment variables A collection of environment variables that can be passed to subprocesses. -.. function:: struct cork_env \*cork_env_new(void) +.. function:: struct cork_env *cork_env_new(void) Create a new, empty collection of environment variables. -.. function:: struct cork_env \*cork_env_clone_current(void) +.. function:: struct cork_env *cork_env_clone_current(void) Create a new :c:type:`cork_env` containing all of the environment variables in the current process's environment list. -.. function:: void cork_env_free(struct cork_env \*env) +.. function:: void cork_env_free(struct cork_env *env) Free a collection of environment variables. -.. function:: const char \*cork_env_get(struct cork_env \*env, const char \*name) +.. function:: const char *cork_env_get(struct cork_env *env, const char *name) Return the value of the environment variable with the given *name*. If there is no variable with that name, return ``NULL``. @@ -70,9 +70,9 @@ Environment variables If *env* is ``NULL``, then the variable is retrieved from the current process environment; otherwise, it is retrieved from *env*. -.. function:: void cork_env_add(struct cork_env \*env, const char \*name, const char \*value) - void cork_env_add_printf(struct cork_env \*env, const char \*name, const char \*format, ...) - void cork_env_add_vprintf(struct cork_env \*env, const char \*name, const char \*format, va_list args) +.. function:: void cork_env_add(struct cork_env *env, const char *name, const char *value) + void cork_env_add_printf(struct cork_env *env, const char *name, const char *format, ...) + void cork_env_add_vprintf(struct cork_env *env, const char *name, const char *format, va_list args) Add a new environment variable with the given *name* and *value*. If there is already a variable with that name, it is overwritten. We make a copy of @@ -83,7 +83,7 @@ Environment variables If *env* is ``NULL``, then the new variable is added to the current process environment; otherwise, it is added to *env*. -.. function:: void cork_env_remove(struct cork_env \*env, const char \*name) +.. function:: void cork_env_remove(struct cork_env *env, const char *name) Remove the environment variable with the given *name*, if it exists. If there isn't any variable with that name, do nothing. @@ -92,7 +92,7 @@ Environment variables environment; otherwise, it is removed from *env*. -.. function:: void cork_env_replace_current(struct cork_env \*env) +.. function:: void cork_env_replace_current(struct cork_env *env) Replace the current process's environment list with the contents of *env*. @@ -107,9 +107,9 @@ Executing another program A specification for executing another program. -.. function:: struct cork_exec \*cork_exec_new(const char \*program) - struct cork_exec \*cork_exec_new_with_params(const char \*program, ...) - struct cork_exec \*cork_exec_new_with_param_array(const char \*program, char \* const \*params) +.. function:: struct cork_exec *cork_exec_new(const char *program) + struct cork_exec *cork_exec_new_with_params(const char *program, ...) + struct cork_exec *cork_exec_new_with_param_array(const char *program, char * const *params) Create a new specification for executing *program*. *program* must either be an absolute path to an executable on the local filesystem, or the name of an @@ -136,24 +136,24 @@ Executing another program This function does not actually execute the program; that is handled by the :c:func:`cork_exec_run` function. -.. function:: void cork_exec_free(struct cork_exec \*exec) +.. function:: void cork_exec_free(struct cork_exec *exec) Free an execution specification. You normally won't need to call this function; normally you'll replace the current process with the new program (by calling :c:func:`cork_exec_run`), which means you won't have a chance to free the specification object. -.. function:: const char \*cork_exec_description(struct cork_exec \*exec) +.. function:: const char *cork_exec_description(struct cork_exec *exec) Return a string description of the program described by an execution specification. -.. function:: void cork_exec_add_param(struct cork_exec \*exec, const char \*param) +.. function:: void cork_exec_add_param(struct cork_exec *exec, const char *param) Add a parameter to the parameter list that will be passed into the new program. -.. function:: void cork_exec_set_env(struct cork_exec \*exec, struct cork_env \*env) +.. function:: void cork_exec_set_env(struct cork_exec *exec, struct cork_env *env) Provide a set of environment variables that will be passed into the new program. The subprocess's environment will contain only those variables @@ -166,18 +166,18 @@ Executing another program If you don't call this function for a specification object, the new program will use the same environment as the calling process. -.. function:: void cork_exec_set_cwd(struct cork_exec \*exec, const char \directory) +.. function:: void cork_exec_set_cwd(struct cork_exec *exec, const char \directory) Change the working directory that the new program will be called from. If you don't call this function for a specification object, the new program will be executed in the same working directory as the calling process. -.. function:: const char \*cork_exec_program(struct cork_exec \*exec) - size_t \*cork_exec_param_count(struct cork_exec \*exec) - const char \*cork_exec_param(struct cork_exec \*exec, size_t index) - struct cork_env \*cork_exec_env(struct cork_exec \*exec) - const char \*cork_exec_cwd(struct cork_exec \*exec) +.. function:: const char *cork_exec_program(struct cork_exec *exec) + size_t *cork_exec_param_count(struct cork_exec *exec) + const char *cork_exec_param(struct cork_exec *exec, size_t index) + struct cork_env *cork_exec_env(struct cork_exec *exec) + const char *cork_exec_cwd(struct cork_exec *exec) Accessor functions that allow you to retrieve the contents of an execution specification. The :c:func:`cork_exec_env` and :c:func:`cork_exec_cwd` @@ -185,7 +185,7 @@ Executing another program directory specified. -.. function:: int cork_exec_run(struct cork_exec \*exec) +.. function:: int cork_exec_run(struct cork_exec *exec) Execute the program specified by *exec*, replacing the current process. If we can successfully start the new program, this function will not return. diff --git a/docs/old/ring-buffer.rst b/docs/old/ring-buffer.rst index 40db587..eaed12e 100644 --- a/docs/old/ring-buffer.rst +++ b/docs/old/ring-buffer.rst @@ -29,8 +29,8 @@ Ring buffers they're added by :c:func:`cork_ring_buffer_add()`. -.. function:: int cork_ring_buffer_init(struct cork_ring_buffer \*buf, size_t size) - struct cork_ring_buffer \*cork_ring_buffer_new(size_t size) +.. function:: int cork_ring_buffer_init(struct cork_ring_buffer *buf, size_t size) + struct cork_ring_buffer *cork_ring_buffer_new(size_t size) Initializes a ring buffer instance, having a capacity of *size* elements. The ``_init`` version should be used to initialize an instance you @@ -39,8 +39,8 @@ Ring buffers the program will abort with an error. -.. function:: void cork_ring_buffer_done(struct cork_ring_buffer \*buf) - void cork_ring_buffer_free(struct cork_ring_buffer \*buf) +.. function:: void cork_ring_buffer_done(struct cork_ring_buffer *buf) + void cork_ring_buffer_free(struct cork_ring_buffer *buf) Finalizes a ring buffer instance. The ``_done`` variant should be used to finalize an instance that you allocated yourself (i.e., on the stack). The @@ -50,22 +50,22 @@ Ring buffers you should do that yourself before calling this function. -.. function:: bool cork_ring_buffer_is_empty(struct cork_ring_buffer \*buf) - bool cork_ring_buffer_is_full(struct cork_ring_buffer \*buf) +.. function:: bool cork_ring_buffer_is_empty(struct cork_ring_buffer *buf) + bool cork_ring_buffer_is_full(struct cork_ring_buffer *buf) Returns whether the ring buffer is empty or full. (You cannot add elements to a full ring buffer, and you cannot pop elemenst from an empty one.) -.. function:: int cork_ring_buffer_add(struct cork_ring_buffer \*buf, void \*element) +.. function:: int cork_ring_buffer_add(struct cork_ring_buffer *buf, void *element) Adds *element* to a ring buffer. If the ring buffer is full, we return ``-1``, and the ring buffer will be unchanged. Otherwise we return ``0``. -.. function:: void \*cork_ring_buffer_pop(struct cork_ring_buffer \*buf) - void \*cork_ring_buffer_peek(struct cork_ring_buffer \*buf) +.. function:: void *cork_ring_buffer_pop(struct cork_ring_buffer *buf) + void *cork_ring_buffer_peek(struct cork_ring_buffer *buf) Returns the next element in the ring buffer. If the ring buffer is empty, we return ``NULL``. The ``_pop`` variant will remove the diff --git a/docs/old/slice.rst b/docs/old/slice.rst index 2d46a5b..f0b3dba 100644 --- a/docs/old/slice.rst +++ b/docs/old/slice.rst @@ -59,7 +59,7 @@ just need to provide an instance of this interface type. that C doesn't have ``try``/``finally`` or RAII, but suck it up and make sure that :c:func:`cork_slice_finish()` gets called. - .. member:: const void \*buf + .. member:: const void *buf The beginning of the sliced portion of the underlying buffer. @@ -67,14 +67,14 @@ just need to provide an instance of this interface type. The size of the sliced portion of the underlying buffer. - .. member:: struct cork_slice_iface \*iface + .. member:: struct cork_slice_iface *iface The slice implementation of the underlying buffer. For slice consumers, this field should be considered private. For slice implementors, you should fill in this field with your slice interface. - .. member:: void \*user_data + .. member:: void *user_data An opaque pointer used by the slice implementation. For slice consumers, this field should be considered private. For slice @@ -82,7 +82,7 @@ just need to provide an instance of this interface type. buffer (and/or any additional metadata that you need.) -.. function:: void cork_slice_clear(struct cork_slice \*slice) +.. function:: void cork_slice_clear(struct cork_slice *slice) Clear a slice object. This fills in a slice instance so that it's “empty”. You should not try to call any of the slice methods on an @@ -90,15 +90,15 @@ just need to provide an instance of this interface type. :c:member:`buf ` pointer. An empty slice is equivalent to a ``NULL`` pointer. -.. function:: bool cork_slice_is_empty(struct cork_slice \*slice) +.. function:: bool cork_slice_is_empty(struct cork_slice *slice) Return whether a slice is empty. -.. function:: int cork_slice_copy(struct cork_slice \*dest, struct cork_slice \*src, size_t offset, size_t length) - int cork_slice_copy_offset(struct cork_slice \*dest, struct cork_slice \*src, size_t offset) - int cork_slice_copy_fast(struct cork_slice \*dest, struct cork_slice \*src, size_t offset, size_t length) - int cork_slice_copy_offset_fast(struct cork_slice \*dest, struct cork_slice \*src, size_t offset) +.. function:: int cork_slice_copy(struct cork_slice *dest, struct cork_slice *src, size_t offset, size_t length) + int cork_slice_copy_offset(struct cork_slice *dest, struct cork_slice *src, size_t offset) + int cork_slice_copy_fast(struct cork_slice *dest, struct cork_slice *src, size_t offset, size_t length) + int cork_slice_copy_offset_fast(struct cork_slice *dest, struct cork_slice *src, size_t offset) Initialize a new slice that refers to a subset of an existing slice. The *offset* and *length* parameters identify the subset. (For the @@ -115,10 +115,10 @@ just need to provide an instance of this interface type. that you call :c:func:`cork_slice_finish()` on *dest* when you are done with it. -.. function:: int cork_slice_light_copy(struct cork_slice \*dest, const struct cork_slice \*src, size_t offset, size_t length) - int cork_slice_light_copy_offset(struct cork_slice \*dest, const struct cork_slice \*src, size_t offset) - int cork_slice_light_copy_fast(struct cork_slice \*dest, const struct cork_slice \*src, size_t offset, size_t length) - int cork_slice_light_copy_offset_fast(struct cork_slice \*dest, const struct cork_slice \*src, size_t offset) +.. function:: int cork_slice_light_copy(struct cork_slice *dest, const struct cork_slice *src, size_t offset, size_t length) + int cork_slice_light_copy_offset(struct cork_slice *dest, const struct cork_slice *src, size_t offset) + int cork_slice_light_copy_fast(struct cork_slice *dest, const struct cork_slice *src, size_t offset, size_t length) + int cork_slice_light_copy_offset_fast(struct cork_slice *dest, const struct cork_slice *src, size_t offset) Initialize a new slice that refers to a subset of an existing slice. By calling a ``_light_copy`` function instead of a ``_copy`` function, you are @@ -142,10 +142,10 @@ just need to provide an instance of this interface type. that you call :c:func:`cork_slice_finish()` on *dest* when you are done with it. -.. function:: int cork_slice_slice(struct cork_slice \*slice, size_t offset, size_t length) - int cork_slice_slice_offset(struct cork_slice \*slice, size_t offset) - int cork_slice_slice_fast(struct cork_slice \*slice, size_t offset, size_t length) - int cork_slice_slice_offset_fast(struct cork_slice \*slice, size_t offset) +.. function:: int cork_slice_slice(struct cork_slice *slice, size_t offset, size_t length) + int cork_slice_slice_offset(struct cork_slice *slice, size_t offset) + int cork_slice_slice_fast(struct cork_slice *slice, size_t offset, size_t length) + int cork_slice_slice_offset_fast(struct cork_slice *slice, size_t offset) Update a slice to refer to a subset of its contents. The *offset* and *length* parameters identify the subset. (For the @@ -158,11 +158,11 @@ just need to provide an instance of this interface type. bounds check for you, and return an error if the requested slice is invalid. -.. function:: void cork_slice_finish(struct cork_slice \*slice) +.. function:: void cork_slice_finish(struct cork_slice *slice) Finalize a slice, freeing the underlying buffer if necessary. -.. function:: int cork_slice_equal(const struct cork_slice \*slice1, const struct cork_slice \*slice2) +.. function:: int cork_slice_equal(const struct cork_slice *slice1, const struct cork_slice *slice2) Compare the contents of two slices for equality. (The *contents* of the slices are compared, not their pointers; this is the slice @@ -176,7 +176,7 @@ Slice interface The interface of methods that slice implementations must provide. - .. member:: void (\*free)(struct cork_slice \*self) + .. member:: void (*free)(struct cork_slice *self) Called when the slice should be freed. If necessary, you should free the contents of the underlying buffer. (If the buffer @@ -186,8 +186,8 @@ Slice interface This function pointer can be ``NULL`` if you don't need to free any underlying buffer. - .. member:: int (\*copy)(struct cork_slice \*dest, const struct cork_slice \*src, size_t offset, size_t length) - int (\*light_copy)(struct cork_slice \*dest, const struct cork_slice \*src, size_t offset, size_t length) + .. member:: int (*copy)(struct cork_slice *dest, const struct cork_slice *src, size_t offset, size_t length) + int (*light_copy)(struct cork_slice *dest, const struct cork_slice *src, size_t offset, size_t length) Create a copy of a slice. You can assume that *offset* and *length* refer to a valid subset of *src*\ 's content. @@ -197,7 +197,7 @@ Slice interface implementations, this lets you create a more light-weight copy — for instance, by not having to make an actualy copy of the underlying buffer. - .. member:: int (\*slice)(struct cork_slice \*self, size_t offset, size_t length) + .. member:: int (*slice)(struct cork_slice *self, size_t offset, size_t length) Update *self* to point at a different subset of the underlying buffer. You can assume that *offset* and *length* refer to a @@ -225,7 +225,7 @@ Several libcork classes can be used to initialize a slice: You can also initialize a slice to point at an existing buffer: -.. function:: void cork_slice_init_static(struct cork_slice \*dest, const void \*buf, size_t size) +.. function:: void cork_slice_init_static(struct cork_slice *dest, const void *buf, size_t size) Initializes *dest* to point at the given static buffer. Since the buffer is static, and guaranteed to always exist, the slice's @@ -243,7 +243,7 @@ You can also initialize a slice to point at an existing buffer: :c:func:`cork_slice_finish` when you're done with the slice. -.. function:: void cork_slice_init_copy_once(struct cork_slice \*dest, const void \*buf, size_t size) +.. function:: void cork_slice_init_copy_once(struct cork_slice *dest, const void *buf, size_t size) Initializes *dest* to point at the given buffer. If any copies are made of the slice, then we create a :ref:`managed copy ` of the diff --git a/docs/old/stream.rst b/docs/old/stream.rst index 145783c..132232e 100644 --- a/docs/old/stream.rst +++ b/docs/old/stream.rst @@ -25,7 +25,7 @@ malformed. If possible, the stream producer can try to recover from the error condition, but more often, the stream producer will simply pass the error back up to its caller. -.. function:: int cork_stream_consumer_data(struct cork_stream_consumer \*consumer, const void \*buf, size_t size, bool is_first_chunk) +.. function:: int cork_stream_consumer_data(struct cork_stream_consumer *consumer, const void *buf, size_t size, bool is_first_chunk) Send the next chunk of data into a stream consumer. You only have to ensure that *buf* is valid for the duration of this function call; the stream @@ -33,13 +33,13 @@ up to its caller. processed later. In particular, this means that it's perfectly safe for *buf* to refer to a stack-allocated memory region. -.. function:: int cork_stream_consumer_eof(struct cork_stream_consumer \*consumer) +.. function:: int cork_stream_consumer_eof(struct cork_stream_consumer *consumer) Notify the stream consumer that the end of the stream has been reached. The stream consumer might perform some final validation and error detection at this point. -.. function:: void cork_stream_consumer_free(struct cork_stream_consumer \*consumer) +.. function:: void cork_stream_consumer_free(struct cork_stream_consumer *consumer) Finalize and deallocate a stream consumer. @@ -49,9 +49,9 @@ Built-in stream producers We provide several built-in stream producers: -.. function:: int cork_consume_fd(struct cork_stream_consumer \*consumer, int fd) - int cork_consume_file(struct cork_stream_consumer \*consumer, FILE \*fp) - int cork_consume_file_from_path(struct cork_stream_consumer \*consumer, const char \*path, int flags) +.. function:: int cork_consume_fd(struct cork_stream_consumer *consumer, int fd) + int cork_consume_file(struct cork_stream_consumer *consumer, FILE *fp) + int cork_consume_file_from_path(struct cork_stream_consumer *consumer, const char *path, int flags) Read in a file, passing its contents into the given stream consumer. The ``_fd`` and ``_file`` variants consume a file that you've already opened; you @@ -118,7 +118,7 @@ To consume data from a stream, you must create a type that implements the stream. Once the stream has been exhausted, the producer will call :c:func:`cork_stream_consumer_eof()` to signal the end of the stream. - .. member:: int (\*data)(struct cork_stream_consumer \*consumer, const void \*buf, size_t size, bool is_first_chunk) + .. member:: int (*data)(struct cork_stream_consumer *consumer, const void *buf, size_t size, bool is_first_chunk) Process the next chunk of data in the stream. *buf* is only guaranteed to be valid for the duration of this function call. If @@ -129,7 +129,7 @@ To consume data from a stream, you must create a type that implements the return ``-1`` and fill in the current error condition using :c:func:`cork_error_set`. - .. member:: int (\*eof)(struct cork_stream_consumer \*consumer) + .. member:: int (*eof)(struct cork_stream_consumer *consumer) Handle the end of the stream. This allows you to defer any final validation or error detection until all of the data has been @@ -139,7 +139,7 @@ To consume data from a stream, you must create a type that implements the ``-1`` and fill in the current error condition using :c:func:`cork_error_set`. - .. member:: void (\*free)(struct cork_stream_consumer \*consumer) + .. member:: void (*free)(struct cork_stream_consumer *consumer) Free the consumer object. @@ -149,9 +149,9 @@ Built-in stream consumers We provide several built-in stream consumers: -.. function:: struct cork_stream_consumer \*cork_fd_consumer_new(int fd) - struct cork_stream_consumer \*cork_file_consumer_new(FILE \*fp) - struct cork_stream_consumer \*cork_file_from_path_consumer_new(const char \*path, int flags) +.. function:: struct cork_stream_consumer *cork_fd_consumer_new(int fd) + struct cork_stream_consumer *cork_file_consumer_new(FILE *fp) + struct cork_stream_consumer *cork_file_from_path_consumer_new(const char *path, int flags) Create a stream consumer that appends any data that it receives to a file. The ``_fd`` and ``_file`` variants append to a file that you've already diff --git a/docs/old/subprocess.rst b/docs/old/subprocess.rst index 2ef0dcf..ded2ef4 100644 --- a/docs/old/subprocess.rst +++ b/docs/old/subprocess.rst @@ -23,7 +23,7 @@ Subprocess objects processes, described below. -.. function:: void cork_subprocess_free(struct cork_subprocess \*sub) +.. function:: void cork_subprocess_free(struct cork_subprocess *sub) Free a subprocess. The subprocess must not currently be executing. @@ -34,8 +34,8 @@ Creating subprocesses There are several functions that you can use to create and execute child processes. -.. function:: struct cork_subprocess \*cork_subprocess_new(void \*user_data, cork_free_f free_user_data, cork_run_f run, struct cork_stream_consumer \*stdout, struct cork_stream_consumer \*stderr, int \*exit_code) - struct cork_subprocess \*cork_subprocess_new_exec(struct cork_exec \*exec, struct cork_stream_consumer \*stdout, struct cork_stream_consumer \*stderr, int \*exit_code) +.. function:: struct cork_subprocess *cork_subprocess_new(void *user_data, cork_free_f free_user_data, cork_run_f run, struct cork_stream_consumer *stdout, struct cork_stream_consumer *stderr, int *exit_code) + struct cork_subprocess *cork_subprocess_new_exec(struct cork_exec *exec, struct cork_stream_consumer *stdout, struct cork_stream_consumer *stderr, int *exit_code) Create a new subprocess specification. The first variant will execute the given *run* function in the subprocess. The second variant will execute a @@ -65,11 +65,11 @@ subprocesses at the same time, and wait for them all to finish. A group of subprocesses that will all be executed simultaneously. -.. function:: struct cork_subprocess_group \*cork_subprocess_group_new(void) +.. function:: struct cork_subprocess_group *cork_subprocess_group_new(void) Create a new group of subprocesses. The group will initially be empty. -.. function:: void cork_subprocess_group_free(struct cork_subprocess_group \*group) +.. function:: void cork_subprocess_group_free(struct cork_subprocess_group *group) Free a subprocess group. This frees all of the subprocesses in the group, too. If you've started executing the subprocesses in the group, you **must @@ -78,7 +78,7 @@ subprocesses at the same time, and wait for them all to finish. is still executing, and the :c:func:`cork_subprocess_group_abort` to terminate the subprocesses before freeing the group.) -.. function:: void cork_subprocess_group_add(struct cork_subprocess_group \*group, struct cork_subprocess \*sub) +.. function:: void cork_subprocess_group_add(struct cork_subprocess_group *group, struct cork_subprocess *sub) Add the given subprocess to *group*. The group takes control of the subprocess; you should not try to free it yourself. @@ -86,8 +86,8 @@ subprocesses at the same time, and wait for them all to finish. Once you've created your subprocesses, you can start them executing: -.. function:: int cork_subprocess_start(struct cork_subprocess \*sub) - int cork_subprocess_group_start(struct cork_subprocess_group \*group) +.. function:: int cork_subprocess_start(struct cork_subprocess *sub) + int cork_subprocess_group_start(struct cork_subprocess_group *group) Execute the given subprocess, or all of the subprocesses in *group*. We immediately return once the processes have been started. You can use the @@ -106,8 +106,8 @@ wait for them to finish. There are two strategies for doing so. If you don't need to communicate with the subprocesses (by writing to their stdin streams or sending them signals), the simplest strategy is to just wait for them to finish: -.. function:: int cork_subprocess_wait(struct cork_subprocess \*sub) - int cork_subprocess_group_wait(struct cork_subprocess_group \*group) +.. function:: int cork_subprocess_wait(struct cork_subprocess *sub) + int cork_subprocess_group_wait(struct cork_subprocess_group *group) Wait until the given subprocess, or all of the subprocesses in *group*, have finished executing. While waiting, we'll continue to read data from the @@ -139,7 +139,7 @@ careful orchestration, you can easily get a deadlock. Moreover, the right pattern of reading and writing depends on the subprocesses that you're executing, so it's not something that we can handle for you automatically.) -.. function:: struct cork_stream_consumer \*cork_subprocess_stdin(struct cork_subprocess \*sub) +.. function:: struct cork_stream_consumer *cork_subprocess_stdin(struct cork_subprocess *sub) Return a :ref:`stream consumer ` that lets you write data to the subprocess's stdin. We do not buffer this data in any way; calling @@ -147,22 +147,22 @@ executing, so it's not something that we can handle for you automatically.) to the subprocess's stdin stream. This can easily lead to deadlock if you do not manage the subprocess's particular orchestration correctly. -.. function:: bool cork_subprocess_is_finished(struct cork_subprocess \*sub) - bool cork_subprocess_group_is_finished(struct cork_subprocess_group \*group) +.. function:: bool cork_subprocess_is_finished(struct cork_subprocess *sub) + bool cork_subprocess_group_is_finished(struct cork_subprocess_group *group) Return whether the given subprocess, or all of the subprocesses in *group*, have finished executing. -.. function:: int cork_subprocess_abort(struct cork_subprocess \*sub) - int cork_subprocess_group_abort(struct cork_subprocess_group \*group) +.. function:: int cork_subprocess_abort(struct cork_subprocess *sub) + int cork_subprocess_group_abort(struct cork_subprocess_group *group) Immediately terminate the given subprocess, or all of the subprocesses in *group*. This can be used to clean up if you detect an error condition and need to close the subprocesses early. If the group has already finished, the function doesn't do anything. -.. function:: bool cork_subprocess_drain(struct cork_subprocess \*sub) - bool cork_subprocess_group_drain(struct cork_subprocess_group \*group) +.. function:: bool cork_subprocess_drain(struct cork_subprocess *sub) + bool cork_subprocess_group_drain(struct cork_subprocess_group *group) Check the given subprocess, or all of the subprocesses in *group*, for any output on their stdout and stderr streams. We'll read in as much data as we diff --git a/docs/old/threads.rst b/docs/old/threads.rst index f79f38e..19bff0b 100644 --- a/docs/old/threads.rst +++ b/docs/old/threads.rst @@ -95,7 +95,7 @@ Every thread goes through the same lifecycle: functions defined below to interact with the thread. -.. function:: struct cork_thread \*cork_thread_new(const char \*name, void \*user_data, cork_free_f free_user_data, cork_run_f run) +.. function:: struct cork_thread *cork_thread_new(const char *name, void *user_data, cork_free_f free_user_data, cork_run_f run) Create a new thread with the given *name* that will execute *run*. The thread does not start running immediately. @@ -119,31 +119,31 @@ Every thread goes through the same lifecycle: yourself once you're sure the thread has finished. -.. function:: void cork_thread_free(struct cork_thread \*thread) +.. function:: void cork_thread_free(struct cork_thread *thread) Free *thread*. You can only call this function if you haven't started the thread yet. Once you start a thread, the thread is responsible for freeing itself when it finishes. -.. function:: struct cork_thread \*cork_current_thread_get(void) +.. function:: struct cork_thread *cork_current_thread_get(void) Return the :c:type:`cork_thread` instance for the current thread. This function returns ``NULL`` when called from the main thread (i.e., the one created automatically when the process starts), or from a thread that wasn't created via :c:func:`cork_thread_new`. -.. function:: const char \* cork_thread_get_name(struct cork_thread \*thread) - cork_thread_id cork_thread_get_id(struct cork_thread \*thread) +.. function:: const char * cork_thread_get_name(struct cork_thread *thread) + cork_thread_id cork_thread_get_id(struct cork_thread *thread) Retrieve information about the given thread. -.. function:: int cork_thread_start(struct cork_thread \*thread) +.. function:: int cork_thread_start(struct cork_thread *thread) Start *thread*. After calling this function, you must not try to free *thread* yourself; the thread will automatically free itself once it has finished executing and has been joined. -.. function:: int cork_thread_join(struct cork_thread \*thread) +.. function:: int cork_thread_join(struct cork_thread *thread) Wait for *thread* to finish executing. If the thread's body's ``run`` function an :ref:`error condition `, we will catch that error and @@ -167,16 +167,16 @@ atomic operations. Addition ~~~~~~~~ -.. function:: int cork_int_atomic_add(volatile int \*var, int delta) - unsigned int cork_uint_atomic_add(volatile unsigned int \*var, unsigned int delta) - size_t cork_size_atomic_add(volatile size_t \*var, size_t delta) +.. function:: int cork_int_atomic_add(volatile int *var, int delta) + unsigned int cork_uint_atomic_add(volatile unsigned int *var, unsigned int delta) + size_t cork_size_atomic_add(volatile size_t *var, size_t delta) Atomically add *delta* to the variable pointed to by *var*, returning the result of the addition. -.. function:: int cork_int_atomic_pre_add(volatile int \*var, int delta) - unsigned int cork_uint_atomic_pre_add(volatile unsigned int \*var, unsigned int delta) - size_t cork_size_atomic_pre_add(volatile size_t \*var, size_t delta) +.. function:: int cork_int_atomic_pre_add(volatile int *var, int delta) + unsigned int cork_uint_atomic_pre_add(volatile unsigned int *var, unsigned int delta) + size_t cork_size_atomic_pre_add(volatile size_t *var, size_t delta) Atomically add *delta* to the variable pointed to by *var*, returning the value from before the addition. @@ -185,16 +185,16 @@ Addition Subtraction ~~~~~~~~~~~ -.. function:: int cork_int_atomic_sub(volatile int \*var, int delta) - unsigned int cork_uint_atomic_sub(volatile unsigned int \*var, unsigned int delta) - size_t cork_size_atomic_sub(volatile size_t \*var, size_t delta) +.. function:: int cork_int_atomic_sub(volatile int *var, int delta) + unsigned int cork_uint_atomic_sub(volatile unsigned int *var, unsigned int delta) + size_t cork_size_atomic_sub(volatile size_t *var, size_t delta) Atomically subtract *delta* from the variable pointed to by *var*, returning the result of the subtraction. -.. function:: int cork_int_atomic_pre_sub(volatile int \*var, int delta) - unsigned int cork_uint_atomic_pre_sub(volatile unsigned int \*var, unsigned int delta) - size_t cork_size_atomic_pre_sub(volatile size_t \*var, size_t delta) +.. function:: int cork_int_atomic_pre_sub(volatile int *var, int delta) + unsigned int cork_uint_atomic_pre_sub(volatile unsigned int *var, unsigned int delta) + size_t cork_size_atomic_pre_sub(volatile size_t *var, size_t delta) Atomically subtract *delta* from the variable pointed to by *var*, returning the value from before the subtraction. @@ -203,10 +203,10 @@ Subtraction Compare-and-swap ~~~~~~~~~~~~~~~~ -.. function:: int cork_int_cas(volatile int_t \*var, int old_value, int new_value) - unsigned int cork_uint_cas(volatile uint_t \*var, unsigned int old_value, unsigned int new_value) - size_t cork_size_cas(volatile size_t \*var, size_t old_value, size_t new_value) - TYPE \*cork_ptr_cas(TYPE \* volatile \*var, TYPE \*old_value, TYPE \*new_value) +.. function:: int cork_int_cas(volatile int_t *var, int old_value, int new_value) + unsigned int cork_uint_cas(volatile uint_t *var, unsigned int old_value, unsigned int new_value) + size_t cork_size_cas(volatile size_t *var, size_t old_value, size_t new_value) + TYPE *cork_ptr_cas(TYPE * volatile *var, TYPE *old_value, TYPE *new_value) Atomically check whether the variable pointed to by *var* contains the value *old_value*, and if so, update it to contain the value diff --git a/docs/old/timestamps.rst b/docs/old/timestamps.rst index 229b5af..01452c2 100644 --- a/docs/old/timestamps.rst +++ b/docs/old/timestamps.rst @@ -26,11 +26,11 @@ High-precision timestamps account the local time zone. -.. function:: void cork_timestamp_init_sec(cork_timestamp \*ts, uint32_t sec) - void cork_timestamp_init_gsec(cork_timestamp \*ts, uint32_t sec, uint32_t gsec) - void cork_timestamp_init_msec(cork_timestamp \*ts, uint32_t sec, uint32_t msec) - void cork_timestamp_init_usec(cork_timestamp \*ts, uint32_t sec, uint32_t usec) - void cork_timestamp_init_nsec(cork_timestamp \*ts, uint32_t sec, uint32_t nsec) +.. function:: void cork_timestamp_init_sec(cork_timestamp *ts, uint32_t sec) + void cork_timestamp_init_gsec(cork_timestamp *ts, uint32_t sec, uint32_t gsec) + void cork_timestamp_init_msec(cork_timestamp *ts, uint32_t sec, uint32_t msec) + void cork_timestamp_init_usec(cork_timestamp *ts, uint32_t sec, uint32_t usec) + void cork_timestamp_init_nsec(cork_timestamp *ts, uint32_t sec, uint32_t nsec) Initializes a timestamp from a separate seconds part and fractional part. For the ``_sec`` variant, the fractional part will be set to @@ -40,7 +40,7 @@ High-precision timestamps microseconds, or nanoseconds, respectively. -.. function:: void cork_timestamp_init_now(cork_timestamp \*ts) +.. function:: void cork_timestamp_init_now(cork_timestamp *ts) Initializes a timestamp with the current UTC time of day. @@ -63,8 +63,8 @@ High-precision timestamps microseconds, or nanoseconds. -.. function:: int cork_timestamp_format_utc(const cork_timestamp ts, const char \*format, struct cork_buffer \*buf) - int cork_timestamp_format_local(const cork_timestamp ts, const char \*format, struct cork_buffer \*buf) +.. function:: int cork_timestamp_format_utc(const cork_timestamp ts, const char *format, struct cork_buffer *buf) + int cork_timestamp_format_local(const cork_timestamp ts, const char *format, struct cork_buffer *buf) Create the string representation of the given timestamp according to *format*, appending the result to the current contents of *buf*. diff --git a/docs/old/unique-ids.rst b/docs/old/unique-ids.rst index 2c55598..b6d3cd4 100644 --- a/docs/old/unique-ids.rst +++ b/docs/old/unique-ids.rst @@ -33,7 +33,7 @@ process. .. macro:: cork_uid_define(SYMBOL id) - cork_uid_define_named(SYMBOL id, const char \*name) + cork_uid_define_named(SYMBOL id, const char *name) You use the :c:func:`cork_uid_define` macro to define a new unique identifier with the given C identifier *id*. The ``_define`` variant also uses *id* as @@ -66,7 +66,7 @@ process. Return a :ref:`hash value ` for the given identifier. -.. function:: const char \*cork_uid_name(const cork_uid id) +.. function:: const char *cork_uid_name(const cork_uid id) Return the name of the given unique identifier. diff --git a/docs/old/versions.rst b/docs/old/versions.rst index fca99cf..64d0b43 100644 --- a/docs/old/versions.rst +++ b/docs/old/versions.rst @@ -34,8 +34,8 @@ libcork version out into separate macros. -.. function:: const char \*cork_version_string(void) - const char \*cork_revision_string(void) +.. function:: const char *cork_version_string(void) + const char *cork_revision_string(void) Return the libcork library version or revision as a string. The *version* is the simple three-part version number (``major:minor:patch``). The