include/gmxfio.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  *                        VERSION 3.2.0
  10  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  11  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  12  * Copyright (c) 2001-2004, The GROMACS development team,
  13  * check out http://www.gromacs.org for more information.
  14
  15  * This program is free software; you can redistribute it and/or
  16  * modify it under the terms of the GNU General Public License
  17  * as published by the Free Software Foundation; either version 2
  18  * of the License, or (at your option) any later version.
  19  *
  20  * If you want to redistribute modifications, please consider that
  21  * scientific software is very special. Version control is crucial -
  22  * bugs must be traceable. We will be happy to consider code for
  23  * inclusion in the official distribution, but derived work must not
  24  * be called official GROMACS. Details are found in the README & COPYING
  25  * files - if they are missing, get the official version at www.gromacs.org.
  26  *
  27  * To help us fund GROMACS development, we humbly ask that you cite
  28  * the papers on the package - you can find them in the top README file.
  29  *
  30  * For more info, check our website at http://www.gromacs.org
  31  *
  32  * And Hey:
  33  * Gromacs Runs On Most of All Computer Systems
  34  */
  35
  36 #ifndef _gmxfio_h
  37 #define _gmxfio_h
  38
  39 #ifdef HAVE_CONFIG_H
  40 #include <config.h>
  41 #endif
  42
  43 #include <stdio.h>
  44 #include "sysstuff.h"
  45 #include "typedefs.h"
  46 #include "xdrf.h"
  47
  48 /* Note that some functions list beow are NOT THREADSAFE
  49  * when multiple threads use the same file pointer.
  50  */
  51
  52 /* Highest number of open input/output files. This is usually limited to 1024 by the OS, anyway. */
  53 #define GMX_MAXFILES    1024
  54
  55 /* Enumerated for different items in files */
  56 enum { eitemHEADER, eitemIR, eitemBOX,
  57        eitemTOP, eitemX, eitemV, eitemF, eitemNR };
  58
  59 /* Enumerated for data types in files */
  60 enum { eioREAL, eioDOUBLE, eioINT, eioGMX_LARGE_INT,
  61        eioUCHAR, eioNUCHAR, eioUSHORT,
  62        eioRVEC, eioNRVEC, eioIVEC, eioSTRING, eioNR };
  63
  64 /* Functions for reading and writing data */
  65 typedef bool do_func(void *item,int nitem,int eio,
  66                      const char *desc,const char *srcfile,int line);
  67
  68 /* Global variables defined in gmxfio.h */
  69 extern do_func *do_read;
  70 extern do_func *do_write;
  71 extern const char *itemstr[eitemNR];
  72 extern const char *comment_str[eitemNR];
  73
  74 /********************************************************
  75  * Open and Close
  76  ********************************************************/
  77
  78 int gmx_fio_open(const char *fn,const char *mode);
  79 /* Open a new file for reading or writing.
  80  * The file type will be deduced from the file name.
  81  * If fn is NULL, stdin / stdout will be used for Ascii I/O (TPA type)
  82  * mode may be "r", "w", or "a". You should append a "b" to the mode
  83  * if you are writing a binary file, but the routine will also
  84  * doublecheck it and try to do it if you forgot. This has no effect on
  85  * unix, but is important on windows.
  86  */
  87
  88 int gmx_fio_close(int fp);
  89 /* Close the file corresponding to fp (if not stdio)
  90  * The routine will exit when an invalid fio is handled.
  91  * Returns 0 on success.
  92  */
  93
  94 int gmx_fio_fp_close(int fp);
  95 /* Close the file corresponding to fp without closing the FIO entry
  96  * Needed e.g. for trxio because the FIO entries are used to store
  97  * additional data.
  98  * NOTE that the fp still needs to be properly closed with gmx_fio_close().
  99  * The routine will exit when an invalid fio is handled.
 100  * Returns 0 on success.
 101  */
 102
 103 void gmx_fio_select(int fp);
 104 /* This routine sets the global variables do_read and do_write
 105  * to point to the correct routines for fp.
 106  */
 107
 108 /********************************************************
 109  * Change properties of the open file
 110  ********************************************************/
 111
 112 extern void gmx_fio_setprecision(int fio,bool bDouble);
 113 /* Select the floating point precision for reading and writing files */
 114
 115 extern char *gmx_fio_getname(int fio);
 116 /* Return the filename corresponding to the fio index */
 117
 118 extern int gmx_fio_getftp(int fio);
 119 /* Return the filetype corresponding to the fio index */
 120
 121 extern void gmx_fio_setftp_fio(int fio,int ftp);
 122 /* And set it */
 123
 124 extern void gmx_fio_setdebug(int fio,bool bDebug);
 125 /* Set the debug mode */
 126
 127 extern bool gmx_fio_getdebug(int fio);
 128 /* Return  whether debug mode is on in fio  */
 129
 130 extern bool gmx_fio_getread(int fio);
 131 /* Return  whether read mode is on in fio  */
 132
 133 /***************************************************
 134  * FILE Operations
 135  ***************************************************/
 136
 137 extern void gmx_fio_rewind(int fio);
 138 /* Rewind the tpa file in fio */
 139
 140 int gmx_fio_flush(int fio);
 141 /* Flush the fio, returns 0 on success */
 142
 143 int gmx_fio_fsync(int fio);
 144 /* fsync the fio, returns 0 on success.
 145    NOTE: don't use fsync function unless you're absolutely sure you need it
 146    because it deliberately interferes with the OS's caching mechanisms and
 147    can cause dramatically slowed down IO performance. Some OSes (Linux,
 148    for example), may implement fsync as a full sync() point. */
 149
 150 extern off_t gmx_fio_ftell(int fio);
 151 /* Return file position if possible */
 152
 153 extern int gmx_fio_seek(int fio,off_t fpos);
 154 /* Set file position if possible, quit otherwise */
 155
 156 extern FILE *gmx_fio_getfp(int fio);
 157 /* Return the file pointer itself */
 158
 159 extern XDR *gmx_fio_getxdr(int fio);
 160 /* Return the file pointer itself */
 161
 162 /* Open a file, return a stream, record the entry in internal FIO object */
 163 FILE * gmx_fio_fopen(const char *fn,const char *mode);
 164
 165 /* Close a file previously opened with gmx_fio_fopen.
 166  * Do not mix these calls with standard fopen/fclose ones!
 167  * Returns 0 on success.
 168  */
 169 int gmx_fio_fclose(FILE *fp);
 170
 171 /* Element with information about position in a currently open file.
 172  * off_t should be defined by autoconf if your system does not have it.
 173  * If you do not have it on some other platform you do not have largefile support
 174  * at all, and you can define it to int (or better, find out how to enable large files).
 175  */
 176 typedef struct
 177 {
 178         char      filename[STRLEN];
 179         off_t     offset;
 180         unsigned char chksum[16];
 181         int       chksum_size;
 182 }
 183 gmx_file_position_t;
 184
 185
 186 /*
 187  * Check if the file position is out of the range of off_t.
 188  * The result is stored along with the other file data of fio.
 189  */
 190 int
 191 gmx_fio_check_file_position(int fio);
 192
 193 /*
 194  * Return the name and file pointer positions for all currently open
 195  * output files. This is used for saving in the checkpoint files, so we
 196  * can truncate output files upon restart-with-appending.
 197  *
 198  * For the first argument you should use a pointer, which will be set to
 199  * point to a list of open files.
 200  */
 201 int
 202 gmx_fio_get_output_file_positions (gmx_file_position_t ** outputfiles,
 203                                    int *nfiles );
 204
 205 /* fsync all open output files. This is used for checkpointing, where
 206    we need to ensure that all output is actually written out to
 207    disk.
 208    This is most important in the case of some networked file systems,
 209    where data is not synced with the file server until close() or
 210    fsync(), so data could remain in cache for days.
 211    Note the caveats reported with gmx_fio_fsync(). */
 212 int gmx_fio_all_output_fsync(void);
 213
 214
 215 int gmx_fio_get_file_md5(int fio, off_t offset,  unsigned char digest[]);
 216
 217
 218 extern int xtc_seek_frame(int frame, int fio, int natoms);
 219
 220 extern int xtc_seek_time(real time, int fio, int natoms);
 221
 222
 223 extern void set_comment(const char *comment);
 224 /* Add this to the comment string for debugging */
 225
 226 extern void unset_comment(void);
 227 /* Remove previously set comment */
 228
 229
 230 /********************************************************
 231  * Dirty C macros... Try this in FORTRAN
 232  * (Oh, and you can do structured programming in C too)
 233  *********************************************************/
 234 #define do_real(item)         (bRead ?\
 235   do_read ((void *)&(item),1,eioREAL,(#item),__FILE__,__LINE__) : \
 236   do_write((void *)&(item),1,eioREAL,(#item),__FILE__,__LINE__))
 237
 238 #define do_double(item)         (bRead ?                                  \
 239   do_read ((void *)&(item),1,eioDOUBLE,(#item),__FILE__,__LINE__) : \
 240   do_write((void *)&(item),1,eioDOUBLE,(#item),__FILE__,__LINE__))
 241
 242 #define do_int(item)          (bRead ?\
 243   do_read ((void *)&(item),1,eioINT,(#item),__FILE__,__LINE__) :\
 244   do_write((void *)&(item),1,eioINT,(#item),__FILE__,__LINE__))
 245
 246 #define do_gmx_large_int(item)          (bRead ?                        \
 247   do_read ((void *)&(item),1,eioGMX_LARGE_INT,(#item),__FILE__,__LINE__) :\
 248   do_write((void *)&(item),1,eioGMX_LARGE_INT,(#item),__FILE__,__LINE__))
 249
 250 #define do_uchar(item)        (bRead ?\
 251   do_read ((void *)&(item),1,eioUCHAR,(#item),__FILE__,__LINE__) :\
 252   do_write((void *)&(item),1,eioUCHAR,(#item),__FILE__,__LINE__))
 253
 254 #define do_nuchar(item,n)     (bRead ?\
 255   do_read ((void *)(item),n,eioNUCHAR,(#item),__FILE__,__LINE__) :\
 256   do_write((void *)(item),n,eioNUCHAR,(#item),__FILE__,__LINE__))
 257
 258 #define do_ushort(item)          (bRead ?\
 259   do_read ((void *)&(item),1,eioUSHORT,(#item),__FILE__,__LINE__) :\
 260   do_write((void *)&(item),1,eioUSHORT,(#item),__FILE__,__LINE__))
 261
 262 #define do_rvec(item)         (bRead ?\
 263   do_read ((void *)(item),1,eioRVEC,(#item),__FILE__,__LINE__) :\
 264   do_write((void *)(item),1,eioRVEC,(#item),__FILE__,__LINE__))
 265
 266 #define do_ivec(item)         (bRead ?\
 267   do_read ((void *)(item),1,eioIVEC,(#item),__FILE__,__LINE__) :\
 268   do_write((void *)(item),1,eioIVEC,(#item),__FILE__,__LINE__))
 269
 270 #define do_string(item)       (bRead ?\
 271   do_read ((void *)(item),1,eioSTRING,(#item),__FILE__,__LINE__) :\
 272   do_write((void *)(item),1,eioSTRING,(#item),__FILE__,__LINE__))
 273
 274 #define ndo_real(item,n,bOK) {\
 275   bOK=TRUE;\
 276   for(i=0; (i<n); i++) {\
 277     char buf[128];\
 278     sprintf(buf,"%s[%d]",#item,i);\
 279     bOK = bOK && (bRead ?\
 280       do_read ((void *)&((item)[i]),1,eioREAL,buf,__FILE__,__LINE__):\
 281       do_write((void *)&(item[i]),1,eioREAL,buf,__FILE__,__LINE__));\
 282   }\
 283 }
 284
 285 #define ndo_double(item,n,bOK) {\
 286   bOK=TRUE;\
 287   for(i=0; (i<n); i++) {\
 288     char buf[128];\
 289     sprintf(buf,"%s[%d]",#item,i);\
 290     bOK = bOK && (bRead ?\
 291       do_read ((void *)&((item)[i]),1,eioDOUBLE,buf,__FILE__,__LINE__):\
 292       do_write((void *)&(item[i]),1,eioDOUBLE,buf,__FILE__,__LINE__));\
 293   }\
 294 }
 295
 296 #define ndo_int(item,n,bOK)  {\
 297   bOK=TRUE;\
 298   for(i=0; (i<n); i++) {\
 299     char buf[128];\
 300     sprintf(buf,"%s[%d]",#item,i);\
 301     bOK = bOK && (bRead ?\
 302       do_read ((void *)&(item[i]),1,eioINT,buf,__FILE__,__LINE__):\
 303       do_write((void *)&(item[i]),1,eioINT,buf,__FILE__,__LINE__));\
 304   }\
 305 }
 306
 307 #define ndo_nuchar(item,n,bOK)  {\
 308   bOK=TRUE;\
 309   for(i=0; (i<n); i++) {\
 310     char buf[128];\
 311     sprintf(buf,"%s[%d]",#item,i);\
 312     bOK = bOK && (bRead ?\
 313       do_read ((void *)&(item[i]),1,eioNUCHAR,buf,__FILE__,__LINE__):\
 314       do_write((void *)&(item[i]),1,eioNUCHAR,buf,__FILE__,__LINE__));\
 315   }\
 316 }
 317
 318 #define ndo_rvec(item,n)      (bRead ?\
 319   do_read ((void *)(item),n,eioNRVEC,(#item),__FILE__,__LINE__) :\
 320   do_write((void *)(item),n,eioNRVEC,(#item),__FILE__,__LINE__))
 321
 322 #define ndo_ivec(item,n,bOK) {\
 323   bOK=TRUE;\
 324   for(i=0; (i<n); i++) {\
 325     char buf[128];\
 326     sprintf(buf,"%s[%d]",#item,i);\
 327     bOK = bOK && (bRead ?\
 328       do_read ((void *)(item)[i],1,eioIVEC,buf,__FILE__,__LINE__):\
 329       do_write((void *)(item)[i],1,eioIVEC,buf,__FILE__,__LINE__));\
 330   }\
 331 }
 332
 333 #define ndo_string(item,n,bOK) {\
 334   bOK=TRUE;\
 335   for(i=0; (i<n); i++) {\
 336     char buf[128];\
 337     sprintf(buf,"%s[%d]",#item,i);\
 338     bOK = bOK && (bRead ?\
 339       do_read ((void *)(item)[i],1,eioSTRING,buf,__FILE__,__LINE__):\
 340       do_write((void *)(item)[i],1,eioSTRING,buf,__FILE__,__LINE__));\
 341   }\
 342 }
 343
 344 #endif