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  * Read a double.
 142  *
 143  * @param h hande to open file
 144  * @param f address of double to read
 145  */
 146 #define GNUNET_BIO_read_double(h, f) (GNUNET_BIO_read_fn (h, __FILE__, __LINE__, \
 147                                                           f, sizeof(double)))
 148
 149
 150 /**
 151  * Read an (u)int32_t.
 152  *
 153  * @param h hande to open file
 154  * @param file name of the source file
 155  * @param line line number in the code
 156  * @param i address of 32-bit integer to read
 157  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 158  */
 159 int
 160 GNUNET_BIO_read_int32__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
 161                          int line, int32_t *i);
 162
 163
 164 /**
 165  * Read an (u)int32_t.
 166  *
 167  * @param h hande to open file
 168  * @param i address of 32-bit integer to read
 169  */
 170 #define GNUNET_BIO_read_int32(h, i) GNUNET_BIO_read_int32__ (h, __FILE__, \
 171                                                              __LINE__, \
 172                                                              (int32_t *) i)
 173
 174
 175 /**
 176  * Read an (u)int64_t.
 177  *
 178  * @param h hande to open file
 179  * @param file name of the source file
 180  * @param line line number in the code
 181  * @param i address of 64-bit integer to read
 182  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 183  */
 184 int
 185 GNUNET_BIO_read_int64__ (struct GNUNET_BIO_ReadHandle *h, const char *file,
 186                          int line, int64_t *i);
 187
 188
 189 /**
 190  * Read an (u)int64_t.
 191  *
 192  * @param h hande to open file
 193  * @param i address of 64-bit integer to read
 194  */
 195 #define GNUNET_BIO_read_int64(h, i) GNUNET_BIO_read_int64__ (h, __FILE__, \
 196                                                              __LINE__, \
 197                                                              (int64_t *) i)
 198
 199
 200 /**
 201  * Handle for buffered writing.
 202  */
 203 struct GNUNET_BIO_WriteHandle;
 204
 205 /**
 206  * Open a file for writing.
 207  *
 208  * @param fn file name to be opened
 209  * @return IO handle on success, NULL on error
 210  */
 211 struct GNUNET_BIO_WriteHandle *
 212 GNUNET_BIO_write_open (const char *fn);
 213
 214
 215 /**
 216  * Close an open file for writing.
 217  *
 218  * @param h file handle
 219  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
 220  */
 221 int
 222 GNUNET_BIO_write_close (struct GNUNET_BIO_WriteHandle *h);
 223
 224
 225 /**
 226  * Write a buffer to a file.
 227  *
 228  * @param h handle to open file
 229  * @param buffer the data to write
 230  * @param n number of bytes to write
 231  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 232  */
 233 int
 234 GNUNET_BIO_write (struct GNUNET_BIO_WriteHandle *h, const void *buffer,
 235                   size_t n);
 236
 237
 238 /**
 239  * Force a buffered writer to flush its buffer
 240  *
 241  * @param h the writer handle
 242  * @return #GNUNET_OK upon success.  Upon failure #GNUNET_SYSERR is returned and
 243  *           the file is closed
 244  */
 245 int
 246 GNUNET_BIO_flush (struct GNUNET_BIO_WriteHandle *h);
 247
 248
 249 /**
 250  * Write a string to a file.
 251  *
 252  * @param h handle to open file
 253  * @param s string to write (can be NULL)
 254  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 255  */
 256 int
 257 GNUNET_BIO_write_string (struct GNUNET_BIO_WriteHandle *h, const char *s);
 258
 259
 260 /**
 261  * Write metadata container to a file.
 262  *
 263  * @param h handle to open file
 264  * @param m metadata to write
 265  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 266  */
 267 int
 268 GNUNET_BIO_write_meta_data (struct GNUNET_BIO_WriteHandle *h,
 269                             const struct GNUNET_CONTAINER_MetaData *m);
 270
 271
 272 /**
 273  * Write a float.
 274  *
 275  * @param h hande to open file
 276  * @param f float to write (must be a variable)
 277  */
 278 #define GNUNET_BIO_write_float(h, f) GNUNET_BIO_write (h, &f, sizeof(float))
 279
 280
 281 /**
 282  * Write a double.
 283  *
 284  * @param h hande to open file
 285  * @param f double to write (must be a variable)
 286  */
 287 #define GNUNET_BIO_write_double(h, f) GNUNET_BIO_write (h, &f, sizeof(double))
 288
 289
 290 /**
 291  * Write an (u)int32_t.
 292  *
 293  * @param h hande to open file
 294  * @param i 32-bit integer to write
 295  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 296  */
 297 int
 298 GNUNET_BIO_write_int32 (struct GNUNET_BIO_WriteHandle *h, int32_t i);
 299
 300
 301 /**
 302  * Write an (u)int64_t.
 303  *
 304  * @param h hande to open file
 305  * @param i 64-bit integer to write
 306  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 307  */
 308 int
 309 GNUNET_BIO_write_int64 (struct GNUNET_BIO_WriteHandle *h, int64_t i);
 310
 311
 312 #if 0                           /* keep Emacsens' auto-indent happy */
 313 {
 314 #endif
 315 #ifdef __cplusplus
 316 }
 317 #endif
 318
 319 /* ifndef GNUNET_BIO_LIB_H */
 320 #endif
 321
 322 /** @} */  /* end of group bio */
 323
 324 /* end of gnunet_bio_lib.h */