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