include/sphinxbase/pio.h

   1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /* ====================================================================
   3  * Copyright (c) 1999-2004 Carnegie Mellon University.  All rights
   4  * reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  *
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  *
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in
  15  *    the documentation and/or other materials provided with the
  16  *    distribution.
  17  *
  18  * This work was supported in part by funding from the Defense Advanced
  19  * Research Projects Agency and the National Science Foundation of the
  20  * United States of America, and the CMU Sphinx Speech Consortium.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND
  23  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  24  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  25  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
  26  * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  *
  34  * ====================================================================
  35  *
  36  */
  37 /*
  38  * pio.h -- Packaged I/O routines.
  39  *
  40  * **********************************************
  41  * CMU ARPA Speech Project
  42  *
  43  * Copyright (c) 1999 Carnegie Mellon University.
  44  * ALL RIGHTS RESERVED.
  45  * **********************************************
  46  *
  47  * HISTORY
  48  * $Log: pio.h,v $
  49  * Revision 1.3  2005/06/22 08:00:09  arthchan2003
  50  * Completed all doxygen documentation on file description for libs3decoder/libutil/libs3audio and programs.
  51  *
  52  * Revision 1.2  2005/06/22 03:09:52  arthchan2003
  53  * 1, Fixed doxygen documentation, 2, Added  keyword.
  54  *
  55  * Revision 1.2  2005/06/16 00:14:08  archan
  56  * Added const keyword to file argument for file_open
  57  *
  58  * Revision 1.1  2005/06/15 06:11:03  archan
  59  * sphinx3 to s3.generic: change io.[ch] to pio.[ch]
  60  *
  61  * Revision 1.5  2005/06/15 04:21:46  archan
  62  * 1, Fixed doxygen-documentation, 2, Add  keyword such that changes will be logged into a file.
  63  *
  64  * Revision 1.4  2005/04/20 03:49:32  archan
  65  * Add const to string argument of myfopen.
  66  *
  67  * Revision 1.3  2005/03/30 01:22:48  archan
  68  * Fixed mistakes in last updates. Add
  69  *
  70  *
  71  * 08-Dec-1999  M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon University
  72  *              Added stat_mtime().
  73  *
  74  * 11-Mar-1999  M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon University
  75  *              Added _myfopen() and myfopen macro.
  76  *
  77  * 05-Sep-97    M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon University
  78  *              Started.
  79  */
  80
  81
  82 #ifndef _LIBUTIL_IO_H_
  83 #define _LIBUTIL_IO_H_
  84
  85 #include <stdio.h>
  86 #if !defined(_WIN32_WCE) && !(defined(__ADSPBLACKFIN__) && !defined(__linux__))
  87 #include <sys/stat.h>
  88 #endif
  89
  90 /* Win32/WinCE DLL gunk */
  91 #include <sphinxbase/sphinxbase_export.h>
  92 #include <sphinxbase/prim_type.h>
  93
  94 /** \file pio.h
  95  * \brief file IO related operations.
  96  *
  97  * Custom fopen with error checking is implemented. fopen_comp can
  98  * open a file with .z, .Z, .gz or .GZ extension
  99  *
 100  * WARNING: Usage of stat_retry will results in 100s of waiting time
 101  * if the file doesn't exist.
 102 */
 103
 104 #ifdef __cplusplus
 105 extern "C" {
 106 #endif
 107 #if 0
 108 /* Fool Emacs. */
 109 }
 110 #endif
 111
 112 /**
 113  * Like fopen, but use popen and zcat if it is determined that "file" is compressed
 114  * (i.e., has a .z, .Z, .gz, or .GZ extension).
 115  */
 116 SPHINXBASE_EXPORT
 117 FILE *fopen_comp (const char *file,             /**< In: File to be opened */
 118                   const char *mode,             /**< In: "r" or "w", as with normal fopen */
 119                   int32 *ispipe /**< Out: On return *ispipe is TRUE iff file
 120                                    was opened via a pipe */
 121         );
 122
 123 /**
 124  * Close a file opened using fopen_comp.
 125  */
 126 SPHINXBASE_EXPORT
 127 void fclose_comp (FILE *fp,             /**< In: File pointer to be closed */
 128                   int32 ispipe  /**< In: ispipe argument that was returned by the
 129                                    corresponding fopen_comp() call */
 130         );
 131
 132 /**
 133  * Open a file for reading, but if file not present try to open compressed version (if
 134  * file is uncompressed, and vice versa).
 135  */
 136 SPHINXBASE_EXPORT
 137 FILE *fopen_compchk (const char *file,  /**< In: File to be opened */
 138                      int32 *ispipe      /**< Out: On return *ispipe is TRUE iff file
 139                                            was opened via a pipe */
 140         );
 141
 142 /**
 143  * Wrapper around fopen to check for failure and E_FATAL if failed.
 144  */
 145 SPHINXBASE_EXPORT
 146 FILE *_myfopen(const char *file, const char *mode,
 147                const char *pgm, int32 line);    /* In: __FILE__, __LINE__ from where called */
 148 #define myfopen(file,mode)      _myfopen((file),(mode),__FILE__,__LINE__)
 149
 150
 151 /**
 152  * NFS file reads seem to fail now and then.  Use the following functions in place of
 153  * the regular fread.  It retries failed freads several times and quits only if all of
 154  * them fail.  Be aware, however, that even normal failures such as attempting to read
 155  * beyond EOF will trigger such retries, wasting about a minute in retries.
 156  * Arguments identical to regular fread.
 157  */
 158 SPHINXBASE_EXPORT
 159 int32 fread_retry(void *pointer, int32 size, int32 num_items, FILE *stream);
 160
 161 /**
 162  * Read a line of arbitrary length from a file and return it as a
 163  * newly allocated string.
 164  *
 165  * @deprecated Use line iterators instead.
 166  *
 167  * @param stream The file handle to read from.
 168  * @param out_len Output: if not NULL, length of the string read.
 169  * @return allocated string containing the line, or NULL on error or EOF.
 170  */
 171 SPHINXBASE_EXPORT
 172 char *fread_line(FILE *stream, size_t *out_len);
 173
 174 /**
 175  * Line iterator for files.
 176  */
 177 typedef struct lineiter_t {
 178         char *buf;
 179         size_t bsiz;
 180         size_t len;
 181         FILE *fh;
 182 } lineiter_t;
 183
 184 /**
 185  * Start reading lines from a file.
 186  */
 187 SPHINXBASE_EXPORT
 188 lineiter_t *lineiter_start(FILE *fh);
 189
 190 /**
 191  * Move to the next line in the file.
 192  */
 193 SPHINXBASE_EXPORT
 194 lineiter_t *lineiter_next(lineiter_t *li);
 195
 196 /**
 197  * Stop reading lines from a file.
 198  */
 199 SPHINXBASE_EXPORT
 200 void lineiter_free(lineiter_t *li);
 201
 202
 203 #ifdef _WIN32_WCE
 204 /* Fake this for WinCE which has no stat() */
 205 #include <windows.h>
 206 struct stat {
 207     DWORD st_mtime;
 208     DWORD st_size;
 209 };
 210 #endif /* _WIN32_WCE */
 211
 212 #if defined(__ADSPBLACKFIN__) && !defined(__linux__)
 213 struct stat {
 214     int32 st_mtime;
 215     int32 st_size;
 216 };
 217
 218 #endif
 219
 220 /**
 221  * Bitstream encoder - for writing compressed files.
 222  */
 223 typedef struct bit_encode_s bit_encode_t;
 224
 225 /**
 226  * Attach bitstream encoder to a file.
 227  */
 228 bit_encode_t *bit_encode_attach(FILE *outfh);
 229
 230 /**
 231  * Retain pointer to a bit encoder.
 232  */
 233 bit_encode_t *bit_encode_retain(bit_encode_t *be);
 234
 235 /**
 236  * Release pointer to a bit encoder.
 237  *
 238  * Note that this does NOT flush any leftover bits.
 239  */
 240 int bit_encode_free(bit_encode_t *be);
 241
 242 /**
 243  * Write bits to encoder.
 244  */
 245 int bit_encode_write(bit_encode_t *be, unsigned char const *bits, int nbits);
 246
 247 /**
 248  * Write lowest-order bits of codeword to encoder.
 249  */
 250 int bit_encode_write_cw(bit_encode_t *be, uint32 codeword, int nbits);
 251
 252 /**
 253  * Flush any unwritten bits, zero-padding if necessary.
 254  */
 255 int bit_encode_flush(bit_encode_t *be);
 256
 257 /**
 258  * There is no bitstream decoder, because a stream abstraction is too
 259  * slow.  Instead we read blocks of bits and treat them as bitvectors.
 260  */
 261
 262 /**
 263  * Like fread_retry, but for stat.  Arguments identical to regular stat.
 264  * Return value: 0 if successful, -1 if stat failed several attempts.
 265  */
 266 SPHINXBASE_EXPORT
 267 int32 stat_retry (const char *file, struct stat *statbuf);
 268
 269 /**
 270  * Return time of last modification for the given file, or -1 if stat fails.
 271  */
 272
 273 SPHINXBASE_EXPORT
 274 int32 stat_mtime (const char *file);
 275
 276 /**
 277  * Create a directory and all of its parent directories, as needed.
 278  *
 279  * @return 0 on success, <0 on failure.
 280  */
 281 SPHINXBASE_EXPORT
 282 int build_directory(const char *path);
 283
 284 #ifdef __cplusplus
 285 }
 286 #endif
 287
 288 #endif