1 files changed, 2 insertions, 161 deletions
diff --git a/doc/disfluid.texi b/doc/disfluid.texi
index bf66908..bf48070 100644
--- a/doc/disfluid.texi
+++ b/doc/disfluid.texi
@@ -7,8 +7,8 @@
 @settitle Demanding Interoperability to Strengthen the Free (Libre) Web: Introducing Disfluid
 @c %**end of header
 
-@set UPDATED 21 March 2023
-@set UPDATED-MONTH March 2023
+@set UPDATED 02 April 2023
+@set UPDATED-MONTH April 2023
 @include version_number.texi
 
 @copying
@@ -219,163 +219,4 @@ NUL-terminated, and the value @code{-2} is returned. Otherwise,
 @code{0} is returned.
 @end deftypefun
 
-@deftp struct disfluid_cache_entry
-A structure that can hold everything related to a cache entry. The
-specific layout is hidden, but the overall size and alignment can be
-queried at run-time.
-@end deftp
-
-@deftypefun size_t disfluid_cache_entry_size (size_t @var{max_key}, size_t @var{max_header}, size_t @var{max_body})
-Return the size to allocate for a cache entry that can hold at most
-@var{max_key} bytes of the key (method, URL and varied header values),
-at most @var{max_header} for the response header, and at most
-@var{max_body} for the response body. Do not hesitate to demand server
-to send terse responses to you. 512 bytes for the key, 4 kB for the
-header, and 2 MB for the body should be more than enough for proper
-cache handling.
-
-This function is a constant function according to GCC: its output only
-depends on the three inputs, and it is not allowed to read global
-data. The compiler is free to reuse the same value without callig the
-function again. Define the @code{ATTRIBUTE_CONST} macro to the syntax
-for function attributes for your compiler. If you use gnulib, use the
-@samp{attribute} module and include @code{attribute.h} before
-@code{disfluid.h} to use this optimization.
-@end deftypefun
-
-@deftypefun size_t disfluid_cache_entry_alignment (void)
-Return the proper alignment for a cache entry. This function is
-constant too.
-@end deftypefun
-
-@deftypefun size_t disfluid_cache_entry_init (struct disfluid_cache_entry *@var{entry}, size_t @var{max_key}, size_t @var{max_header}, size_t @var{max_body})
-Initialize the @var{entry}, that must be aligned properly, and
-allocated with an appropriate size, such as given by
-@code{disfluid_cache_entry_size}.
-@end deftypefun
-
-@deftypefun void disfluid_cache_entry_minimum_size (const struct disfluid_cache_entry *@var{entry}, size_t *@var{min_key}, size_t *@var{min_header}, size_t *@var{min_body})
-Set @var{min_key}, @var{min_header} and @var{min_body} to the minimum
-sizes that should be allocated to hold the key, header and body of
-@var{entry}.
-@end deftypefun
-
-@deftypefun int disfluid_cache_entry_copy (struct disfluid_cache_entry *@var{dest}, const struct disfluid_cache_entry *@var{src})
-Copy @var{src} to @var{dest}. If one of the @var{dest} limits is too
-short, return a negative error code. Otherwise, return 0.
-
-@table @code
-@item -1, -3, -5, -7
-indicates that the key does not fit in @var{dest};
-@item -2, -3, -6, -7
-indicates that the response header does not fit in @var{dest};
-@item -4, -5, -6, -7
-indicates that the response body does not fit in @var{dest}.
-@end table
-@end deftypefun
-
-@deftypefun {struct disfluid_cache_entry *} disfluid_cache_entry_alloc (size_t @var{max_key}, size_t @var{max_header}, size_t @var{max_body})
-@deftypefunx {struct disfluid_cache_entry *} disfluid_cache_entry_dup (const struct disfluid_cache_entry *@var{src})
-Allocate a new cache entry with the libc standard
-allocator. @code{disfluid_cache_entry_dup} allocates the same limits
-as those of @var{src}.
-@end deftypefun
-
-@deftypefun void disfluid_cache_entry_free (struct disfluid_cache_entry *@var{entry})
-Free a cache entry allocated with the standard libc allocator.
-@end deftypefun
-
-To make memory allocation a bit safer, you can use the
-@code{DISFLUID_CACHE_ENTRY_ALLOC (@var{ptr}, @var{max_key},
-@var{max_header}, @var{max_body})} and
-@code{DISFLUID_CACHE_ENTRY_FREE(@var{ptr})} macros as:
-
-@example
-struct disfluid_cache_entry *entry;
-if (DISFLUID_CACHE_ENTRY_ALLOC (entry, 512, 4096, 2 * 1024 * 1024) < 0)
-  @{
-    /* Handle memory allocation failure */
-  @}
-else
-  @{
-    /* Do something with entry… */
-  @}
-DISFLUID_CACHE_ENTRY_FREE (entry);
-/* entry is set to NULL */
-assert (entry == NULL);
-@end example
-
-@deftypefun void disfluid_cache_entry_set_request_date (struct disfluid_cache_entry *@var{entry}, const struct timespec *@var{request_date})
-@deftypefunx void disfluid_cache_entry_set_response_date (struct disfluid_cache_entry *@var{entry}, const struct timespec *@var{response_date})
-@deftypefunx void disfluid_cache_entry_set_invalidated (struct disfluid_cache_entry *@var{entry}, int @var{invalidated})
-@deftypefunx void disfluid_cache_entry_invalidate (struct disfluid_cache_entry *@var{entry})
-Manage the metadata associated with @var{entry}.
-@end deftypefun
-
-@deftypefun int disfluid_cache_entry_set_key (struct disfluid_cache_entry *@var{entry}, const char *@var{key})
-@deftypefunx int disfluid_cache_entry_set_header (struct disfluid_cache_entry *@var{entry}, const char *@var{header})
-@deftypefunx int disfluid_cache_entry_set_body (struct disfluid_cache_entry *@var{entry}, size_t @var{body_length}, const char *@var{body})
-Try and set the relevant cache entry section in @var{entry}. If the
-respective limit is too short, return a negative error
-code. Otherwise, return 0.
-@end deftypefun
-
-@deftypefun void disfluid_cache_entry_get_request_date (const struct disfluid_cache_entry *@var{entry}, struct timespec *@var{request_date})
-@deftypefunx void disfluid_cache_entry_get_response_date (const struct disfluid_cache_entry *@var{entry}, struct timespec *@var{response_date})
-@deftypefunx int disfluid_cache_entry_is_invalidated (const struct disfluid_cache_entry *@var{entry})
-Query the metadata of @var{entry}.
-@end deftypefun
-
-@deftypefun size_t disfluid_cache_entry_get_key (const struct disfluid_cache_entry *@var{entry}, size_t @var{start}, size_t @var{max}, char *@var{dst})
-@deftypefunx size_t disfluid_cache_entry_get_header (const struct disfluid_cache_entry *@var{entry}, size_t @var{start}, size_t @var{max}, char *@var{dst})
-@deftypefunx size_t disfluid_cache_entry_get_body (const struct disfluid_cache_entry *@var{entry}, size_t @var{start}, size_t @var{max}, char *@var{dst})
-Ignore the first @var{start} bytes, and copy the next bytes of the
-relevant section in @var{entry}, up to @var{max}, to @var{dst}. Return
-the total length of the section. If there is more room allocated, make
-sure that @var{dst} is NUL-terminated.
-@end deftypefun
-
-@deftypefun int disfluid_cache_entry_load (struct disfluid_cache_entry *@var{entry}, int @var{load_key}, int @var{load_header}, int @var{load_body}, ssize_t (*@var{read_impl}) (void *, void *, size_t), int (*@var{skip}) (void *, size_t), void *@var{context})
-@deftypefunx int disfluid_cache_entry_read (struct disfluid_cache_entry *@var{entry}, int @var{load_key}, int @var{load_header}, int @var{load_body}, int @var{fd})
-@deftypefunx int disfluid_cache_entry_fread (struct disfluid_cache_entry *@var{entry}, int @var{load_key}, int @var{load_header}, int @var{load_body}, FILE *@var{handle})
-Load a file to set up @var{entry}. If @var{load_key} (respectively,
-@var{load_header} and @var{load_body}) is a strictly positive value,
-then attempt to read the key (respectively, the header and body). If
-it is 0, then skip it, but keep the previously loaded value. If it is
-negative, then erase the value. The specific
-@code{disfluid_cache_entry_read} and @code{disfluid_cache_entry_fread}
-use a file descriptor and a stream file handle respectively, instead
-of custom callbacks.
-
-@code{disfluid_cache_entry_load} uses custom callbacks to read the
-file. The file is passed as @var{context}, and during the calls to
-@var{read_impl} and @var{skip}, it is bound to the first argument. The
-second argument of @var{read_impl} is bound to a buffer where to read
-the bytes. The last argument is bound to the read request size, in
-bytes.
-
-@var{read_impl} is supposed to return a negative value if a file
-system failure occurs, 0 if the file is at end, or a value at most
-equal to the read request, and set the bytes in the buffer
-accordingly. @var{skip} is supposed to return 0 on success and advance
-the file pointer by the request size, or return a negative error code.
-
-The loading functions return 0 on success, -1 in case of a file system
-error, -2 if the file is invalid, -3 if it is incomplete, -4 if the
-key is too large, -5 if the header is too large, -6 if the body is too
-large.
-@end deftypefun
-
-@deftypefun int disfluid_cache_entry_save (const struct disfluid_cache_entry *@var{entry}, ssize_t (*@var{write_impl}) (void *, const void *, size_t), void *@var{context})
-@deftypefunx int disfluid_cache_entry_write (const struct disfluid_cache_entry *@var{entry}, int @var{fd})
-@deftypefunx int disfluid_cache_entry_fwrite (const struct disfluid_cache_entry *@var{entry}, FILE *@var{handle})
-Save @var{entry} to a file. Return 0 on success, -1 if writing to the
-file raised an error, -2 if the key, header or body is unset in
-@var{entry}. @var{write_impl} is called with @var{context} bound to
-the first argument, an array of bytes to write as the second, and the
-array length as the third. It should return a negative value to signal
-an error, or a value at most the write request length, and write the
-corresponding bytes in the request to file.
-@end deftypefun
-
 @bye