bgzf.h

   1 /*
   2  * The Broad Institute
   3  * SOFTWARE COPYRIGHT NOTICE AGREEMENT
   4  * This software and its documentation are copyright 2008 by the
   5  * Broad Institute/Massachusetts Institute of Technology. All rights are reserved.
   6  *
   7  * This software is supplied without any warranty or guaranteed support whatsoever.
   8  * Neither the Broad Institute nor MIT can be responsible for its use, misuse,
   9  * or functionality.
  10  */
  11
  12 #ifndef __BGZF_H
  13 #define __BGZF_H
  14
  15 #include <stdint.h>
  16 #include <stdio.h>
  17 #include <stdbool.h>
  18 #include <zlib.h>
  19 #ifdef _USE_KNETFILE
  20 #include "knetfile.h"
  21 #endif
  22
  23 //typedef int8_t bool;
  24
  25 typedef struct {
  26     int file_descriptor;
  27     char open_mode;  // 'r' or 'w'
  28     bool owned_file, is_uncompressed;
  29 #ifdef _USE_KNETFILE
  30         union {
  31                 knetFile *fpr;
  32                 FILE *fpw;
  33         } x;
  34 #else
  35     FILE* file;
  36 #endif
  37     int uncompressed_block_size;
  38     int compressed_block_size;
  39     void* uncompressed_block;
  40     void* compressed_block;
  41     int64_t block_address;
  42     int block_length;
  43     int block_offset;
  44         int cache_size;
  45     const char* error;
  46         void *cache; // a pointer to a hash table
  47 } BGZF;
  48
  49 #ifdef __cplusplus
  50 extern "C" {
  51 #endif
  52
  53 /*
  54  * Open an existing file descriptor for reading or writing.
  55  * Mode must be either "r" or "w".
  56  * A subsequent bgzf_close will not close the file descriptor.
  57  * Returns null on error.
  58  */
  59 BGZF* bgzf_fdopen(int fd, const char* __restrict mode);
  60
  61 /*
  62  * Open the specified file for reading or writing.
  63  * Mode must be either "r" or "w".
  64  * Returns null on error.
  65  */
  66 BGZF* bgzf_open(const char* path, const char* __restrict mode);
  67
  68 /*
  69  * Close the BGZ file and free all associated resources.
  70  * Does not close the underlying file descriptor if created with bgzf_fdopen.
  71  * Returns zero on success, -1 on error.
  72  */
  73 int bgzf_close(BGZF* fp);
  74
  75 /*
  76  * Read up to length bytes from the file storing into data.
  77  * Returns the number of bytes actually read.
  78  * Returns zero on end of file.
  79  * Returns -1 on error.
  80  */
  81 int bgzf_read(BGZF* fp, void* data, int length);
  82
  83 /*
  84  * Write length bytes from data to the file.
  85  * Returns the number of bytes written.
  86  * Returns -1 on error.
  87  */
  88 int bgzf_write(BGZF* fp, const void* data, int length);
  89
  90 /*
  91  * Return a virtual file pointer to the current location in the file.
  92  * No interpetation of the value should be made, other than a subsequent
  93  * call to bgzf_seek can be used to position the file at the same point.
  94  * Return value is non-negative on success.
  95  * Returns -1 on error.
  96  */
  97 int64_t bgzf_tell(BGZF* fp);
  98
  99 /*
 100  * Set the file to read from the location specified by pos, which must
 101  * be a value previously returned by bgzf_tell for this file (but not
 102  * necessarily one returned by this file handle).
 103  * The where argument must be SEEK_SET.
 104  * Seeking on a file opened for write is not supported.
 105  * Returns zero on success, -1 on error.
 106  */
 107 int64_t bgzf_seek(BGZF* fp, int64_t pos, int where);
 108
 109 /*
 110  * Set the cache size. Zero to disable. By default, caching is
 111  * disabled. The recommended cache size for frequent random access is
 112  * about 8M bytes.
 113  */
 114 void bgzf_set_cache_size(BGZF *fp, int cache_size);
 115
 116 #ifdef __cplusplus
 117 }
 118 #endif
 119
 120 #endif