src/include/gnunet_bio_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Buffered IO library
  26  *
  27  * @defgroup bio  BIO library
  28  * Buffered binary disk IO (with endianess conversion)
  29  * @{
  30  */
  31
  32 #ifndef GNUNET_BIO_LIB_H
  33 #define GNUNET_BIO_LIB_H
  34
  35 #include "gnunet_container_lib.h"
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #if 0                           /* keep Emacsens' auto-indent happy */
  41 }
  42 #endif
  43 #endif
  44
  45 /**
  46  * Handle for buffered reading.
  47  */
  48 struct GNUNET_BIO_ReadHandle;
  49
  50
  51 /**
  52  * Open a file for reading.
  53  *
  54  * @param fn file name to be opened
  55  * @return IO handle on success, NULL on error
  56  */
  57 struct GNUNET_BIO_ReadHandle *
  58 GNUNET_BIO_read_open (const char *fn);
  59
  60
  61 /**
  62  * Close an open file.  Reports if any errors reading
  63  * from the file were encountered.
  64  *
  65  * @param h file handle
  66  * @param emsg set to the error message
  67  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
  68  */
  69 int
  70 GNUNET_BIO_read_close (struct GNUNET_BIO_ReadHandle *h, char **emsg);
  71
  72
  73 /**
  74  * Read the contents of a binary file into a buffer.
  75  *
  76  * @param h handle to an open file
  77  * @param what describes what is being read (for error message creation)
  78  * @param result the buffer to write the result to
  79  * @param len the number of bytes to read
  80  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
  81  */
  82 int
  83 GNUNET_BIO_read (struct GNUNET_BIO_ReadHandle *h, const char *what,
  84                  void *result, size_t len);
  85
  86
  87 /**
  88  * Read the contents of a binary file into a buffer.
  89  *
  90  * @param h handle to an open file
  91  * @param file name of the source file
  92  * @param line line number in the source file
  93  * @param result the buffer to write the result to
  94  * @param len the number of bytes to read
  95  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
  96  */
  97 int
  98 GNUNET_BIO_read_fn (struct GNUNET_BIO_ReadHandle *h,
  99                     const char *file, int line,
 100                     void *result, size_t len);
 101
 102 /**
 103  * Read 0-terminated string from a file.
 104  *
 105  * @param h handle to an open file
 106  * @param what describes what is being read (for error message creation)
 107  * @param result the buffer to store a pointer to the (allocated) string to
 108  *        (note that *result could be set to NULL as well)
 109  * @param max_length maximum allowed length for the string
 110  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 111  */
 112 int
 113 GNUNET_BIO_read_string (struct GNUNET_BIO_ReadHandle *h, const char *what,
 114                         char **result, size_t max_length);
 115
 116
 117 /**
 118  * Read metadata container from a file.
 119  *
 120  * @param h handle to an open file
 121  * @param what describes what is being read (for error message creation)
 122  * @param result the buffer to store a pointer to the (allocated) metadata
 123  * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure
 124  */
 125 int
 126 GNUNET_BIO_read_meta_data (struct GNUNET_BIO_ReadHandle *h, const char *what,
 127                            struct GNUNET_CONTAINER_MetaData **result);
 128
 129
 130 /**
 131  * Read a float.
 132  *
 133  * @param h hande to open file
 134  * @param f address of float to read
 135  */
 136 #define GNUNET_BIO_read_float(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, \
 137                                                          f, sizeof(float)))
 138
 139
 140
 141 /**
 142  * Read a double.
 143  *
 144  * @param h hande to open file
 145  * @param f address of double to read
 146  */
 147 #define GNUNET_BIO_read_double(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, \
 148                                                           f, sizeof(double)))
 149
 150
 151 /**
 152  * Read an (u)int32_t.
 153  *
 154  * @param h hande to open file
 155  * @param file name of the source file
 156  * @param line line number in the code
 157  * @param i address of 32-bit integer to read
 158  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 159  */
 160 int
 161 GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
 162                          int line, int32_t *i);
 163
 164
 165 /**
 166  * Read an (u)int32_t.
 167  *
 168  * @param h hande to open file
 169  * @param i address of 32-bit integer to read
 170  */
 171 #define GNUNET_BIO_read_int32(h, i) GNUNET_BIO_read_int32__ (h, __FILE__, \
 172                                                              __LINE__, \
 173                                                              (int32_t*) i)
 174
 175
 176 /**
 177  * Read an (u)int64_t.
 178  *
 179  * @param h hande to open file
 180  * @param file name of the source file
 181  * @param line line number in the code
 182  * @param i address of 64-bit integer to read
 183  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 184  */
 185 int
 186 GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
 187                          int line, int64_t *i);
 188
 189
 190 /**
 191  * Read an (u)int64_t.
 192  *
 193  * @param h hande to open file
 194  * @param i address of 64-bit integer to read
 195  */
 196 #define GNUNET_BIO_read_int64(h, i) GNUNET_BIO_read_int64__ (h, __FILE__, \
 197                                                              __LINE__, \
 198                                                              (int64_t*) i)
 199
 200
 201 /**
 202  * Handle for buffered writing.
 203  */
 204 struct GNUNET_BIO_WriteHandle;
 205
 206 /**
 207  * Open a file for writing.
 208  *
 209  * @param fn file name to be opened
 210  * @return IO handle on success, NULL on error
 211  */
 212 struct GNUNET_BIO_WriteHandle *
 213 GNUNET_BIO_write_open (const char *fn);
 214
 215
 216 /**
 217  * Close an open file for writing.
 218  *
 219  * @param h file handle
 220  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
 221  */
 222 int
 223 GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h);
 224
 225
 226 /**
 227  * Write a buffer to a file.
 228  *
 229  * @param h handle to open file
 230  * @param buffer the data to write
 231  * @param n number of bytes to write
 232  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 233  */
 234 int
 235 GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, const void *buffer,
 236                   size_t n);
 237
 238
 239 /**
 240  * Force a buffered writer to flush its buffer
 241  *
 242  * @param h the writer handle
 243  * @return #GNUNET_OK upon success.  Upon failure #GNUNET_SYSERR is returned and
 244  *           the file is closed
 245  */
 246 int
 247 GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h);
 248
 249
 250 /**
 251  * Write a string to a file.
 252  *
 253  * @param h handle to open file
 254  * @param s string to write (can be NULL)
 255  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 256  */
 257 int
 258 GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, const char *s);
 259
 260
 261 /**
 262  * Write metadata container to a file.
 263  *
 264  * @param h handle to open file
 265  * @param m metadata to write
 266  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 267  */
 268 int
 269 GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h,
 270                             const struct GNUNET_CONTAINER_MetaData *m);
 271
 272
 273
 274 /**
 275  * Write a float.
 276  *
 277  * @param h hande to open file
 278  * @param f float to write (must be a variable)
 279  */
 280 #define GNUNET_BIO_write_float(h, f) GNUNET_BIO_write (h, &f, sizeof(float))
 281
 282
 283
 284 /**
 285  * Write a double.
 286  *
 287  * @param h hande to open file
 288  * @param f double to write (must be a variable)
 289  */
 290 #define GNUNET_BIO_write_double(h, f) GNUNET_BIO_write (h, &f, sizeof(double))
 291
 292
 293 /**
 294  * Write an (u)int32_t.
 295  *
 296  * @param h hande to open file
 297  * @param i 32-bit integer to write
 298  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 299  */
 300 int
 301 GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, int32_t i);
 302
 303
 304 /**
 305  * Write an (u)int64_t.
 306  *
 307  * @param h hande to open file
 308  * @param i 64-bit integer to write
 309  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 310  */
 311 int
 312 GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, int64_t i);
 313
 314
 315 #if 0                           /* keep Emacsens' auto-indent happy */
 316 {
 317 #endif
 318 #ifdef __cplusplus
 319 }
 320 #endif
 321
 322 /* ifndef GNUNET_BIO_LIB_H */
 323 #endif
 324
 325 /** @} */  /* end of group bio */
 326
 327 /* end of gnunet_bio_lib.h */