X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_bio_lib.h;h=e90e85832786510b137386c2256be503982afa9d;hb=f1e8076ed474a429aff32839ed5f8fc20371839c;hp=f70baa0701a57e3b8864fce11aed31f6033cf384;hpb=09cfcd83bd680bd5178c7fead1c6927fcf45b352;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_bio_lib.h b/src/include/gnunet_bio_lib.h index f70baa070..e90e85832 100644 --- a/src/include/gnunet_bio_lib.h +++ b/src/include/gnunet_bio_lib.h @@ -1,27 +1,32 @@ /* This file is part of GNUnet. - (C) 2009 Christian Grothoff (and other contributing authors) + Copyright (C) 2009 GNUnet e.V. - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 2, or (at your - option) any later version. + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU Affero General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + SPDX-License-Identifier: AGPL3.0-or-later */ /** - * @file include/gnunet_bio_lib.h - * @brief buffered IO API * @author Christian Grothoff + * + * @file + * Buffered IO library + * + * @defgroup bio BIO library + * Buffered binary disk IO (with endianess conversion) + * @{ */ #ifndef GNUNET_BIO_LIB_H @@ -49,7 +54,8 @@ struct GNUNET_BIO_ReadHandle; * @param fn file name to be opened * @return IO handle on success, NULL on error */ -struct GNUNET_BIO_ReadHandle *GNUNET_BIO_read_open (const char *fn); +struct GNUNET_BIO_ReadHandle * +GNUNET_BIO_read_open (const char *fn); /** @@ -58,10 +64,10 @@ struct GNUNET_BIO_ReadHandle *GNUNET_BIO_read_open (const char *fn); * * @param h file handle * @param emsg set to the error message - * @return GNUNET_OK on success, GNUNET_SYSERR otherwise + * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise */ -int GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, - char **emsg); +int +GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, char **emsg); /** @@ -71,12 +77,27 @@ int GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, * @param what describes what is being read (for error message creation) * @param result the buffer to write the result to * @param len the number of bytes to read - * @return GNUNET_OK on success, GNUNET_SYSERR on failure + * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure */ -int GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, - const char *what, - void *result, - size_t len); +int +GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, const char *what, + void *result, size_t len); + + +/** + * Read the contents of a binary file into a buffer. + * + * @param h handle to an open file + * @param file name of the source file + * @param line line number in the source file + * @param result the buffer to write the result to + * @param len the number of bytes to read + * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure + */ +int +GNUNET_BIO_read_fn (struct GNUNET_BIO_ReadHandle *h, + const char *file, int line, + void *result, size_t len); /** * Read 0-terminated string from a file. @@ -85,13 +106,12 @@ int GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, * @param what describes what is being read (for error message creation) * @param result the buffer to store a pointer to the (allocated) string to * (note that *result could be set to NULL as well) - * @param maxLen maximum allowed length for the string - * @return GNUNET_OK on success, GNUNET_SYSERR on failure + * @param max_length maximum allowed length for the string + * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure */ -int GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, - const char *what, - char **result, - size_t maxLen); +int +GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, const char *what, + char **result, size_t max_length); /** @@ -100,11 +120,11 @@ int GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, * @param h handle to an open file * @param what describes what is being read (for error message creation) * @param result the buffer to store a pointer to the (allocated) metadata - * @return GNUNET_OK on success, GNUNET_SYSERR on failure + * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure */ -int GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, - const char *what, - struct GNUNET_CONTAINER_MetaData **result); +int +GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, const char *what, + struct GNUNET_CONTAINER_MetaData **result); /** @@ -112,8 +132,8 @@ int GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, * * @param h hande to open file * @param f address of float to read - */ -#define GNUNET_BIO_read_float(h, f) (GNUNET_BIO_read (h, __FILE__ "##__LINE__##", f, sizeof(float))) + */ +#define GNUNET_BIO_read_float(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(float))) @@ -122,21 +142,22 @@ int GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, * * @param h hande to open file * @param f address of double to read - */ -#define GNUNET_BIO_read_double(h, f) (GNUNET_BIO_read (h, __FILE__ "##__LINE__##", f, sizeof(double))) + */ +#define GNUNET_BIO_read_double(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, f, sizeof(double))) /** * Read an (u)int32_t. * * @param h hande to open file - * @param what describes what is being read (for error message creation) + * @param file name of the source file + * @param line line number in the code * @param i address of 32-bit integer to read - * @return GNUNET_OK on success, GNUNET_SYSERR on error - */ -int GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, - const char *what, - int32_t *i); + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ +int +GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, const char *file, + int line, int32_t * i); /** @@ -144,21 +165,22 @@ int GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, * * @param h hande to open file * @param i address of 32-bit integer to read - */ -#define GNUNET_BIO_read_int32(h, i) GNUNET_BIO_read_int32__ (h, __FILE__ "##__LINE__##", (int32_t*) i) + */ +#define GNUNET_BIO_read_int32(h, i) GNUNET_BIO_read_int32__ (h, __FILE__, __LINE__, (int32_t*) i) /** * Read an (u)int64_t. * * @param h hande to open file - * @param what describes what is being read (for error message creation) + * @param file name of the source file + * @param line line number in the code * @param i address of 64-bit integer to read - * @return GNUNET_OK on success, GNUNET_SYSERR on error - */ -int GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, - const char *what, - int64_t *i); + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ +int +GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, const char *file, + int line, int64_t * i); /** @@ -166,21 +188,23 @@ int GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, * * @param h hande to open file * @param i address of 64-bit integer to read - */ -#define GNUNET_BIO_read_int64(h, i) GNUNET_BIO_read_int64__ (h, __FILE__ "##__LINE__##", (int64_t*) i) + */ +#define GNUNET_BIO_read_int64(h, i) GNUNET_BIO_read_int64__ (h, __FILE__, __LINE__, (int64_t*) i) /** * Handle for buffered writing. */ struct GNUNET_BIO_WriteHandle; + /** * Open a file for writing. * * @param fn file name to be opened * @return IO handle on success, NULL on error */ -struct GNUNET_BIO_WriteHandle *GNUNET_BIO_write_open (const char *fn); +struct GNUNET_BIO_WriteHandle * +GNUNET_BIO_write_open (const char *fn); /** @@ -189,7 +213,8 @@ struct GNUNET_BIO_WriteHandle *GNUNET_BIO_write_open (const char *fn); * @param h file handle * @return GNUNET_OK on success, GNUNET_SYSERR otherwise */ -int GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h); +int +GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h); /** @@ -198,11 +223,22 @@ int GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h); * @param h handle to open file * @param buffer the data to write * @param n number of bytes to write - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ +int +GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, const void *buffer, + size_t n); + + +/** + * Force a buffered writer to flush its buffer + * + * @param h the writer handle + * @return #GNUNET_OK upon success. Upon failure #GNUNET_SYSERR is returned and + * the file is closed */ -int GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, - const void *buffer, - size_t n); +int +GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h); /** @@ -210,12 +246,10 @@ int GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, * * @param h handle to open file * @param s string to write (can be NULL) - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ -int GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, - const char *s); - - +int +GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, const char *s); /** @@ -223,10 +257,11 @@ int GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, * * @param h handle to open file * @param m metadata to write - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ -int GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h, - const struct GNUNET_CONTAINER_MetaData *m); +int +GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h, + const struct GNUNET_CONTAINER_MetaData *m); @@ -235,7 +270,7 @@ int GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h, * * @param h hande to open file * @param f float to write (must be a variable) - */ + */ #define GNUNET_BIO_write_float(h, f) GNUNET_BIO_write (h, &f, sizeof(float)) @@ -245,7 +280,7 @@ int GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h, * * @param h hande to open file * @param f double to write (must be a variable) - */ + */ #define GNUNET_BIO_write_double(h, f) GNUNET_BIO_write (h, &f, sizeof(double)) @@ -253,22 +288,22 @@ int GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h, * Write an (u)int32_t. * * @param h hande to open file - * @param i address of 32-bit integer to write - * @return GNUNET_OK on success, GNUNET_SYSERR on error - */ -int GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, - int32_t i); + * @param i 32-bit integer to write + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ +int +GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, int32_t i); /** * Write an (u)int64_t. * * @param h hande to open file - * @param i address of 64-bit integer to write - * @return GNUNET_OK on success, GNUNET_SYSERR on error - */ -int GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, - int64_t i); + * @param i 64-bit integer to write + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ +int +GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, int64_t i); #if 0 /* keep Emacsens' auto-indent happy */ @@ -280,4 +315,7 @@ int GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, /* ifndef GNUNET_BIO_LIB_H */ #endif + +/** @} */ /* end of group bio */ + /* end of gnunet_bio_lib.h */