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 extern off_t gmx_fio_ftell(int fio);
 144 /* Return file position if possible */
 145
 146 extern int gmx_fio_seek(int fio,off_t fpos);
 147 /* Set file position if possible, quit otherwise */
 148
 149 extern FILE *gmx_fio_getfp(int fio);
 150 /* Return the file pointer itself */
 151
 152 extern XDR *gmx_fio_getxdr(int fio);
 153 /* Return the file pointer itself */
 154
 155 /* Open a file, return a stream, record the entry in internal FIO object */
 156 FILE * gmx_fio_fopen(const char *fn,const char *mode);
 157
 158 /* Close a file previously opened with gmx_fio_fopen.
 159  * Do not mix these calls with standard fopen/fclose ones!
 160  * Returns 0 on success.
 161  */
 162 int gmx_fio_fclose(FILE *fp);
 163
 164 /* Element with information about position in a currently open file.
 165  * off_t should be defined by autoconf if your system does not have it.
 166  * If you do not have it on some other platform you do not have largefile support
 167  * at all, and you can define it to int (or better, find out how to enable large files).
 168  */
 169 typedef struct
 170 {
 171         char      filename[STRLEN];
 172         off_t     offset;
 173         unsigned char chksum[16];
 174         int       chksum_size;
 175 }
 176 gmx_file_position_t;
 177
 178
 179 /*
 180  * Check if the file position is out of the range of off_t.
 181  * The result is stored along with the other file data of fio.
 182  */
 183 int
 184 gmx_fio_check_file_position(int fio);
 185
 186 /*
 187  * Return the name and file pointer positions for all currently open
 188  * output files. This is used for saving in the checkpoint files, so we
 189  * can truncate output files upon restart-with-appending.
 190  *
 191  * For the first argument you should use a pointer, which will be set to
 192  * point to a list of open files.
 193  */
 194 int
 195 gmx_fio_get_output_file_positions (gmx_file_position_t ** outputfiles,
 196                                    int *nfiles );
 197
 198 int gmx_fio_get_file_md5(int fio, off_t offset,  unsigned char digest[]);
 199
 200
 201 extern int xtc_seek_frame(int frame, int fio, int natoms);
 202
 203 extern int xtc_seek_time(real time, int fio, int natoms);
 204
 205
 206 extern void set_comment(const char *comment);
 207 /* Add this to the comment string for debugging */
 208
 209 extern void unset_comment(void);
 210 /* Remove previously set comment */
 211
 212
 213 /********************************************************
 214  * Dirty C macros... Try this in FORTRAN
 215  * (Oh, and you can do structured programming in C too)
 216  *********************************************************/
 217 #define do_real(item)         (bRead ?\
 218   do_read ((void *)&(item),1,eioREAL,(#item),__FILE__,__LINE__) : \
 219   do_write((void *)&(item),1,eioREAL,(#item),__FILE__,__LINE__))
 220
 221 #define do_double(item)         (bRead ?                                  \
 222   do_read ((void *)&(item),1,eioDOUBLE,(#item),__FILE__,__LINE__) : \
 223   do_write((void *)&(item),1,eioDOUBLE,(#item),__FILE__,__LINE__))
 224
 225 #define do_int(item)          (bRead ?\
 226   do_read ((void *)&(item),1,eioINT,(#item),__FILE__,__LINE__) :\
 227   do_write((void *)&(item),1,eioINT,(#item),__FILE__,__LINE__))
 228
 229 #define do_gmx_large_int(item)          (bRead ?                        \
 230   do_read ((void *)&(item),1,eioGMX_LARGE_INT,(#item),__FILE__,__LINE__) :\
 231   do_write((void *)&(item),1,eioGMX_LARGE_INT,(#item),__FILE__,__LINE__))
 232
 233 #define do_uchar(item)        (bRead ?\
 234   do_read ((void *)&(item),1,eioUCHAR,(#item),__FILE__,__LINE__) :\
 235   do_write((void *)&(item),1,eioUCHAR,(#item),__FILE__,__LINE__))
 236
 237 #define do_nuchar(item,n)     (bRead ?\
 238   do_read ((void *)(item),n,eioNUCHAR,(#item),__FILE__,__LINE__) :\
 239   do_write((void *)(item),n,eioNUCHAR,(#item),__FILE__,__LINE__))
 240
 241 #define do_ushort(item)          (bRead ?\
 242   do_read ((void *)&(item),1,eioUSHORT,(#item),__FILE__,__LINE__) :\
 243   do_write((void *)&(item),1,eioUSHORT,(#item),__FILE__,__LINE__))
 244
 245 #define do_rvec(item)         (bRead ?\
 246   do_read ((void *)(item),1,eioRVEC,(#item),__FILE__,__LINE__) :\
 247   do_write((void *)(item),1,eioRVEC,(#item),__FILE__,__LINE__))
 248
 249 #define do_ivec(item)         (bRead ?\
 250   do_read ((void *)(item),1,eioIVEC,(#item),__FILE__,__LINE__) :\
 251   do_write((void *)(item),1,eioIVEC,(#item),__FILE__,__LINE__))
 252
 253 #define do_string(item)       (bRead ?\
 254   do_read ((void *)(item),1,eioSTRING,(#item),__FILE__,__LINE__) :\
 255   do_write((void *)(item),1,eioSTRING,(#item),__FILE__,__LINE__))
 256
 257 #define ndo_real(item,n,bOK) {\
 258   bOK=TRUE;\
 259   for(i=0; (i<n); i++) {\
 260     char buf[128];\
 261     sprintf(buf,"%s[%d]",#item,i);\
 262     bOK = bOK && (bRead ?\
 263       do_read ((void *)&((item)[i]),1,eioREAL,buf,__FILE__,__LINE__):\
 264       do_write((void *)&(item[i]),1,eioREAL,buf,__FILE__,__LINE__));\
 265   }\
 266 }
 267
 268 #define ndo_double(item,n,bOK) {\
 269   bOK=TRUE;\
 270   for(i=0; (i<n); i++) {\
 271     char buf[128];\
 272     sprintf(buf,"%s[%d]",#item,i);\
 273     bOK = bOK && (bRead ?\
 274       do_read ((void *)&((item)[i]),1,eioDOUBLE,buf,__FILE__,__LINE__):\
 275       do_write((void *)&(item[i]),1,eioDOUBLE,buf,__FILE__,__LINE__));\
 276   }\
 277 }
 278
 279 #define ndo_int(item,n,bOK)  {\
 280   bOK=TRUE;\
 281   for(i=0; (i<n); i++) {\
 282     char buf[128];\
 283     sprintf(buf,"%s[%d]",#item,i);\
 284     bOK = bOK && (bRead ?\
 285       do_read ((void *)&(item[i]),1,eioINT,buf,__FILE__,__LINE__):\
 286       do_write((void *)&(item[i]),1,eioINT,buf,__FILE__,__LINE__));\
 287   }\
 288 }
 289
 290 #define ndo_nuchar(item,n,bOK)  {\
 291   bOK=TRUE;\
 292   for(i=0; (i<n); i++) {\
 293     char buf[128];\
 294     sprintf(buf,"%s[%d]",#item,i);\
 295     bOK = bOK && (bRead ?\
 296       do_read ((void *)&(item[i]),1,eioNUCHAR,buf,__FILE__,__LINE__):\
 297       do_write((void *)&(item[i]),1,eioNUCHAR,buf,__FILE__,__LINE__));\
 298   }\
 299 }
 300
 301 #define ndo_rvec(item,n)      (bRead ?\
 302   do_read ((void *)(item),n,eioNRVEC,(#item),__FILE__,__LINE__) :\
 303   do_write((void *)(item),n,eioNRVEC,(#item),__FILE__,__LINE__))
 304
 305 #define ndo_ivec(item,n,bOK) {\
 306   bOK=TRUE;\
 307   for(i=0; (i<n); i++) {\
 308     char buf[128];\
 309     sprintf(buf,"%s[%d]",#item,i);\
 310     bOK = bOK && (bRead ?\
 311       do_read ((void *)(item)[i],1,eioIVEC,buf,__FILE__,__LINE__):\
 312       do_write((void *)(item)[i],1,eioIVEC,buf,__FILE__,__LINE__));\
 313   }\
 314 }
 315
 316 #define ndo_string(item,n,bOK) {\
 317   bOK=TRUE;\
 318   for(i=0; (i<n); i++) {\
 319     char buf[128];\
 320     sprintf(buf,"%s[%d]",#item,i);\
 321     bOK = bOK && (bRead ?\
 322       do_read ((void *)(item)[i],1,eioSTRING,buf,__FILE__,__LINE__):\
 323       do_write((void *)(item)[i],1,eioSTRING,buf,__FILE__,__LINE__));\
 324   }\
 325 }
 326
 327 #endif