Merge branch 'master' of git.gromacs.org:gromacs
[gromacs/rigid-bodies.git] / include / gmxfio.h
blob41955a85aaff99dc68e5f41df483173db8d8ded6
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.
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.
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.
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.
30 * For more info, check our website at http://www.gromacs.org
32 * And Hey:
33 * Gromacs Runs On Most of All Computer Systems
36 #ifndef _gmxfio_h
37 #define _gmxfio_h
39 #ifdef HAVE_CONFIG_H
40 #include <config.h>
41 #endif
43 #include <stdio.h>
44 #include "sysstuff.h"
45 #include "typedefs.h"
46 #include "xdrf.h"
48 /* types */
50 /* Enumerated for different items in files */
51 enum { eitemHEADER, eitemIR, eitemBOX,
52 eitemTOP, eitemX, eitemV, eitemF, eitemNR };
54 /* Enumerated for data types in files */
55 enum { eioREAL, eioDOUBLE, eioINT, eioGMX_LARGE_INT,
56 eioUCHAR, eioNUCHAR, eioUSHORT,
57 eioRVEC, eioNRVEC, eioIVEC, eioSTRING, eioNR };
59 typedef struct t_fileio t_fileio;
61 extern const char *itemstr[eitemNR];
62 extern const char *comment_str[eitemNR];
65 /********************************************************
66 * Open and Close
67 ********************************************************/
69 t_fileio *gmx_fio_open(const char *fn,const char *mode);
70 /* Open a new file for reading or writing.
71 * The file type will be deduced from the file name.
72 * If fn is NULL, stdin / stdout will be used for Ascii I/O (TPA type)
73 * mode may be "r", "w", or "a". You should append a "b" to the mode
74 * if you are writing a binary file, but the routine will also
75 * doublecheck it and try to do it if you forgot. This has no effect on
76 * unix, but is important on windows.
79 int gmx_fio_close(t_fileio *fp);
80 /* Close the file corresponding to fp (if not stdio)
81 * The routine will exit when an invalid fio is handled.
82 * Returns 0 on success.
85 int gmx_fio_fp_close(t_fileio *fp);
86 /* Close the file corresponding to fp without closing the FIO entry
87 * Needed e.g. for trxio because the FIO entries are used to store
88 * additional data.
89 * NOTE that the fp still needs to be properly closed with gmx_fio_close().
90 * The routine will exit when an invalid fio is handled.
91 * Returns 0 on success.
95 /* Open a file, return a stream, record the entry in internal FIO object */
96 FILE* gmx_fio_fopen(const char *fn,const char *mode);
98 /* Close a file previously opened with gmx_fio_fopen.
99 * Do not mix these calls with standard fopen/fclose ones!
100 * Returns 0 on success. */
101 int gmx_fio_fclose(FILE *fp);
105 /********************************************************
106 * Change properties of the open file
107 ********************************************************/
109 extern void gmx_fio_setprecision(t_fileio *fio,bool bDouble);
110 /* Select the floating point precision for reading and writing files */
112 extern char *gmx_fio_getname(t_fileio *fio);
113 /* Return the filename corresponding to the fio index */
115 extern int gmx_fio_getftp(t_fileio *fio);
116 /* Return the filetype corresponding to the fio index.
117 There is as of now no corresponding setftp function because the file
118 was opened as a specific file type and changing that midway is most
119 likely an evil hack. */
121 extern void gmx_fio_setdebug(t_fileio *fio,bool bDebug);
122 /* Set the debug mode */
124 extern bool gmx_fio_getdebug(t_fileio *fio);
125 /* Return whether debug mode is on in fio */
127 extern bool gmx_fio_getread(t_fileio *fio);
128 /* Return whether read mode is on in fio */
131 extern void gmx_fio_checktype(t_fileio *fio);
132 /* Check whether the fio is of a sane type */
134 /***************************************************
135 * FILE Operations
136 ***************************************************/
138 extern void gmx_fio_rewind(t_fileio *fio);
139 /* Rewind the tpa file in fio */
141 int gmx_fio_flush(t_fileio *fio);
142 /* Flush the fio, returns 0 on success */
144 int gmx_fio_fsync(t_fileio *fio);
145 /* fsync the fio, returns 0 on success.
146 NOTE: don't use fsync function unless you're absolutely sure you need it
147 because it deliberately interferes with the OS's caching mechanisms and
148 can cause dramatically slowed down IO performance. Some OSes (Linux,
149 for example), may implement fsync as a full sync() point. */
151 extern off_t gmx_fio_ftell(t_fileio *fio);
152 /* Return file position if possible */
154 extern int gmx_fio_seek(t_fileio *fio,off_t fpos);
155 /* Set file position if possible, quit otherwise */
157 extern FILE *gmx_fio_getfp(t_fileio *fio);
158 /* Return the file pointer itself */
160 extern XDR *gmx_fio_getxdr(t_fileio *fio);
161 /* Return the file pointer itself */
167 /* Element with information about position in a currently open file.
168 * off_t should be defined by autoconf if your system does not have it.
169 * If you do not have it on some other platform you do not have largefile
170 * support at all, and you can define it to int (or better, find out how to
171 * enable large files). */
172 typedef struct
174 char filename[STRLEN];
175 off_t offset;
176 unsigned char chksum[16];
177 int chksum_size;
179 gmx_file_position_t;
182 int gmx_fio_check_file_position(t_fileio *fio);
183 /* Check if the file position is out of the range of off_t.
184 * The result is stored along with the other file data of fio.
187 int gmx_fio_get_output_file_positions(gmx_file_position_t ** outputfiles,
188 int *nfiles );
189 /* Return the name and file pointer positions for all currently open
190 * output files. This is used for saving in the checkpoint files, so we
191 * can truncate output files upon restart-with-appending.
193 * For the first argument you should use a pointer, which will be set to
194 * point to a list of open files.
197 t_fileio *gmx_fio_all_output_fsync(void);
198 /* fsync all open output files. This is used for checkpointing, where
199 we need to ensure that all output is actually written out to
200 disk.
201 This is most important in the case of some networked file systems,
202 where data is not synced with the file server until close() or
203 fsync(), so data could remain in cache for days.
204 Note the caveats reported with gmx_fio_fsync().
206 returns: NULL if no error occurred, or a pointer to the first file that
207 failed if an error occurred
211 int gmx_fio_get_file_md5(t_fileio *fio, off_t offset, unsigned char digest[]);
214 extern int xtc_seek_frame(t_fileio *fio, int frame, int natoms);
216 extern int xtc_seek_time(t_fileio *fio, real time, int natoms);
219 /* Add this to the comment string for debugging */
220 extern void gmx_fio_set_comment(t_fileio *fio, const char *comment);
222 /* Remove previously set comment */
223 extern void gmx_fio_unset_comment(t_fileio *fio);
228 /********************************************************
229 * Read and write
230 ********************************************************/
233 /* basic reading & writing */
234 bool gmx_fio_reade_real(t_fileio *fio, real *item,
235 const char *desc, const char *srcfile, int line);
236 bool gmx_fio_reade_double(t_fileio *fio, double *item,
237 const char *desc, const char *srcfile, int line);
238 bool gmx_fio_reade_int(t_fileio *fio, int *item,
239 const char *desc, const char *srcfile, int line);
240 bool gmx_fio_reade_gmx_large_int(t_fileio *fio, gmx_large_int_t *item,
241 const char *desc, const char *srcfile, int line);
242 bool gmx_fio_reade_uchar(t_fileio *fio, unsigned char *item,
243 const char *desc, const char *srcfile, int line);
244 bool gmx_fio_reade_ushort(t_fileio *fio, unsigned short *item,
245 const char *desc, const char *srcfile, int line);
246 bool gmx_fio_reade_rvec(t_fileio *fio, rvec *item,
247 const char *desc, const char *srcfile, int line);
248 bool gmx_fio_reade_ivec(t_fileio *fio, ivec *item,
249 const char *desc, const char *srcfile, int line);
250 bool gmx_fio_reade_string(t_fileio *fio, char *item,
251 const char *desc, const char *srcfile, int line);
253 bool gmx_fio_writee_real(t_fileio *fio, real item,
254 const char *desc, const char *srcfile, int line);
255 bool gmx_fio_writee_double(t_fileio *fio, double item,
256 const char *desc, const char *srcfile, int line);
257 bool gmx_fio_writee_int(t_fileio *fio, int item,
258 const char *desc, const char *srcfile, int line);
259 bool gmx_fio_writee_gmx_large_int(t_fileio *fio, gmx_large_int_t item,
260 const char *desc, const char *srcfile, int line);
261 bool gmx_fio_writee_uchar(t_fileio *fio, unsigned char item,
262 const char *desc, const char *srcfile, int line);
263 bool gmx_fio_writee_ushort(t_fileio *fio, unsigned short item,
264 const char *desc, const char *srcfile, int line);
265 bool gmx_fio_writee_rvec(t_fileio *fio, rvec *item,
266 const char *desc, const char *srcfile, int line);
267 bool gmx_fio_writee_ivec(t_fileio *fio, ivec *item,
268 const char *desc, const char *srcfile, int line);
269 bool gmx_fio_writee_string(t_fileio *fio, const char *item,
270 const char *desc, const char *srcfile, int line);
272 /* reading or writing, depending on the file's opening mode string */
273 bool gmx_fio_doe_real(t_fileio *fio, real *item,
274 const char *desc, const char *srcfile, int line);
275 bool gmx_fio_doe_double(t_fileio *fio, double *item,
276 const char *desc, const char *srcfile, int line);
277 bool gmx_fio_doe_bool(t_fileio *fio, bool *item,
278 const char *desc, const char *srcfile, int line);
279 bool gmx_fio_doe_int(t_fileio *fio, int *item,
280 const char *desc, const char *srcfile, int line);
281 bool gmx_fio_doe_gmx_large_int(t_fileio *fio, gmx_large_int_t *item,
282 const char *desc, const char *srcfile, int line);
283 bool gmx_fio_doe_uchar(t_fileio *fio, unsigned char *item,
284 const char *desc, const char *srcfile, int line);
285 bool gmx_fio_doe_ushort(t_fileio *fio, unsigned short *item,
286 const char *desc, const char *srcfile, int line);
287 bool gmx_fio_doe_rvec(t_fileio *fio, rvec *item,
288 const char *desc, const char *srcfile, int line);
289 bool gmx_fio_doe_ivec(t_fileio *fio, ivec *item,
290 const char *desc, const char *srcfile, int line);
291 bool gmx_fio_doe_string(t_fileio *fio, char *item,
292 const char *desc, const char *srcfile, int line);
297 /* array reading & writing */
298 bool gmx_fio_nreade_real(t_fileio *fio, real *item, int n,
299 const char *desc, const char *srcfile, int line);
300 bool gmx_fio_nreade_double(t_fileio *fio, double *item, int n,
301 const char *desc, const char *srcfile, int line);
302 bool gmx_fio_nreade_int(t_fileio *fio, int *item, int n,
303 const char *desc, const char *srcfile, int line);
304 bool gmx_fio_nreade_gmx_large_int(t_fileio *fio, gmx_large_int_t *item, int n,
305 const char *desc, const char *srcfile,
306 int line);
307 bool gmx_fio_nreade_uchar(t_fileio *fio, unsigned char *item, int n,
308 const char *desc, const char *srcfile, int line);
309 bool gmx_fio_nreade_ushort(t_fileio *fio, unsigned short *item, int n,
310 const char *desc, const char *srcfile, int line);
311 bool gmx_fio_nreade_rvec(t_fileio *fio, rvec *item, int n,
312 const char *desc, const char *srcfile, int line);
313 bool gmx_fio_nreade_ivec(t_fileio *fio, ivec *item, int n,
314 const char *desc, const char *srcfile, int line);
315 bool gmx_fio_nreade_string(t_fileio *fio, char *item[], int n,
316 const char *desc, const char *srcfile, int line);
318 bool gmx_fio_nwritee_real(t_fileio *fio, const real *item, int n,
319 const char *desc, const char *srcfile, int line);
320 bool gmx_fio_nwritee_double(t_fileio *fio, const double *item, int n,
321 const char *desc, const char *srcfile, int line);
322 bool gmx_fio_nwritee_int(t_fileio *fio, const int *item, int n,
323 const char *desc, const char *srcfile, int line);
324 bool gmx_fio_nwritee_gmx_large_int(t_fileio *fio,
325 const gmx_large_int_t *item, int n,
326 const char *desc, const char *srcfile,
327 int line);
328 bool gmx_fio_nwritee_uchar(t_fileio *fio, const unsigned char *item, int n,
329 const char *desc, const char *srcfile, int line);
330 bool gmx_fio_nwritee_ushort(t_fileio *fio, const unsigned short *item, int n,
331 const char *desc, const char *srcfile, int line);
332 bool gmx_fio_nwritee_rvec(t_fileio *fio, const rvec *item, int n,
333 const char *desc, const char *srcfile, int line);
334 bool gmx_fio_nwritee_ivec(t_fileio *fio, const ivec *item, int n,
335 const char *desc, const char *srcfile, int line);
336 bool gmx_fio_nwritee_string(t_fileio *fio, const char *item[], int n,
337 const char *desc, const char *srcfile, int line);
339 bool gmx_fio_ndoe_real(t_fileio *fio, real *item, int n,
340 const char *desc, const char *srcfile, int line);
341 bool gmx_fio_ndoe_double(t_fileio *fio, double *item, int n,
342 const char *desc, const char *srcfile, int line);
343 bool gmx_fio_ndoe_bool(t_fileio *fio, bool *item, int n,
344 const char *desc, const char *srcfile, int line);
345 bool gmx_fio_ndoe_int(t_fileio *fio, int *item, int n,
346 const char *desc, const char *srcfile, int line);
347 bool gmx_fio_ndoe_gmx_large_int(t_fileio *fio, gmx_large_int_t *item, int n,
348 const char *desc, const char *srcfile,
349 int line);
350 bool gmx_fio_ndoe_uchar(t_fileio *fio, unsigned char *item, int n,
351 const char *desc, const char *srcfile, int line);
352 bool gmx_fio_ndoe_ushort(t_fileio *fio, unsigned short *item, int n,
353 const char *desc, const char *srcfile, int line);
354 bool gmx_fio_ndoe_rvec(t_fileio *fio, rvec *item, int n,
355 const char *desc, const char *srcfile, int line);
356 bool gmx_fio_ndoe_ivec(t_fileio *fio, ivec *item, int n,
357 const char *desc, const char *srcfile, int line);
358 bool gmx_fio_ndoe_string(t_fileio *fio, char *item[], int n,
359 const char *desc, const char *srcfile, int line);
363 /* convenience macros */
364 #define gmx_fio_read_real(fio, item) gmx_fio_reade_real(fio, &item, (#item), __FILE__, __LINE__)
365 #define gmx_fio_read_double(fio, item) gmx_fio_reade_double(fio, &item, (#item), __FILE__, __LINE__)
366 #define gmx_fio_read_int(fio, item) gmx_fio_reade_int(fio, &item, (#item), __FILE__, __LINE__)
367 #define gmx_fio_read_gmx_large_int(fio, item) gmx_fio_reade_gmx_large_int(fio, &item, (#item), __FILE__, __LINE__)
368 #define gmx_fio_read_uchar(fio, item) gmx_fio_reade_uchar(fio, &item, (#item), __FILE__, __LINE__)
369 #define gmx_fio_read_ushort(fio, item) gmx_fio_reade_ushort(fio, &item, (#item), __FILE__, __LINE__)
370 #define gmx_fio_read_rvec(fio, item) gmx_fio_reade_rvec(fio, item, (#item), __FILE__, __LINE__)
371 #define gmx_fio_read_ivec(fio, item) gmx_fio_reade_ivec(fio, item, (#item), __FILE__, __LINE__)
372 #define gmx_fio_read_string(fio, item) gmx_fio_reade_string(fio, item, (#item), __FILE__, __LINE__)
374 #define gmx_fio_write_real(fio, item) gmx_fio_writee_real(fio, item, (#item), __FILE__, __LINE__)
375 #define gmx_fio_write_double(fio, item) gmx_fio_writee_double(fio, item, (#item), __FILE__, __LINE__)
376 #define gmx_fio_write_int(fio, item) gmx_fio_writee_int(fio, item, (#item), __FILE__, __LINE__)
377 #define gmx_fio_write_gmx_large_int(fio, item) gmx_fio_writee_gmx_large_int(fio, item, (#item), __FILE__, __LINE__)
378 #define gmx_fio_write_uchar(fio, item) gmx_fio_writee_uchar(fio, item, (#item), __FILE__, __LINE__)
379 #define gmx_fio_write_ushort(fio, item) gmx_fio_writee_ushort(fio, item, (#item), __FILE__, __LINE__)
380 #define gmx_fio_write_rvec(fio, item) gmx_fio_writee_rvec(fio, item, (#item), __FILE__, __LINE__)
381 #define gmx_fio_write_ivec(fio, item) gmx_fio_writee_ivec(fio, item, (#item), __FILE__, __LINE__)
382 #define gmx_fio_write_string(fio, item) gmx_fio_writee_string(fio, item, (#item), __FILE__, __LINE__)
384 #define gmx_fio_do_real(fio, item) gmx_fio_doe_real(fio, &item, (#item), __FILE__, __LINE__)
385 #define gmx_fio_do_double(fio, item) gmx_fio_doe_double(fio, &item, (#item), __FILE__, __LINE__)
386 #define gmx_fio_do_bool(fio, item) gmx_fio_doe_bool(fio, &item, (#item), __FILE__, __LINE__)
387 #define gmx_fio_do_int(fio, item) gmx_fio_doe_int(fio, &item, (#item), __FILE__, __LINE__)
388 #define gmx_fio_do_gmx_large_int(fio, item) gmx_fio_doe_gmx_large_int(fio, &item, (#item), __FILE__, __LINE__)
389 #define gmx_fio_do_uchar(fio, item) gmx_fio_doe_uchar(fio, &item, (#item), __FILE__, __LINE__)
390 #define gmx_fio_do_ushort(fio, item) gmx_fio_doe_ushort(fio, &item, (#item), __FILE__, __LINE__)
391 #define gmx_fio_do_rvec(fio, item) gmx_fio_doe_rvec(fio, &item, (#item), __FILE__, __LINE__)
392 #define gmx_fio_do_ivec(fio, item) gmx_fio_doe_ivec(fio, &item, (#item), __FILE__, __LINE__)
393 #define gmx_fio_do_string(fio, item) gmx_fio_doe_string(fio, item, (#item), __FILE__, __LINE__)
398 #define gmx_fio_nread_real(fio, item, n) gmx_fio_nreade_real(fio, item, n, (#item), __FILE__, __LINE__)
399 #define gmx_fio_nread_double(fio, item, n) gmx_fio_nreade_double(fio, item, n, (#item), __FILE__, __LINE__)
400 #define gmx_fio_nread_int(fio, item, n) gmx_fio_nreade_int(fio, item, n, (#item), __FILE__, __LINE__)
401 #define gmx_fio_nread_gmx_large_int(fio, item, n) gmx_fio_nreade_gmx_large_int(fio, item, n, (#item), __FILE__, __LINE__)
402 #define gmx_fio_nread_uchar(fio, item, n) gmx_fio_nreade_uchar(fio, item, n, (#item), __FILE__, __LINE__)
403 #define gmx_fio_nread_ushort(fio, item, n) gmx_fio_nreade_ushort(fio, item, n, (#item), __FILE__, __LINE__)
404 #define gmx_fio_nread_rvec(fio, item, n) gmx_fio_nreade_rvec(fio, item, n, (#item), __FILE__, __LINE__)
405 #define gmx_fio_nread_ivec(fio, item, n) gmx_fio_nreade_ivec(fio, item, n, (#item), __FILE__, __LINE__)
406 #define gmx_fio_nread_string(fio, item, n) gmx_fio_nreade_string(fio, item, n, (#item), __FILE__, __LINE__)
408 #define gmx_fio_nwrite_real(fio, item, n) gmx_fio_nwritee_real(fio, item, n, (#item), __FILE__, __LINE__)
409 #define gmx_fio_nwrite_double(fio, item, n) gmx_fio_nwritee_double(fio, item, n, (#item), __FILE__, __LINE__)
410 #define gmx_fio_nwrite_int(fio, item, n) gmx_fio_nwritee_int(fio, item, n, (#item), __FILE__, __LINE__)
411 #define gmx_fio_nwrite_gmx_large_int(fio, item, n) gmx_fio_nwritee_gmx_large_int(fio, item, n, (#item), __FILE__, __LINE__)
412 #define gmx_fio_nwrite_uchar(fio, item, n) gmx_fio_nwritee_uchar(fio, item, n, (#item), __FILE__, __LINE__)
413 #define gmx_fio_nwrite_ushort(fio, item, n) gmx_fio_nwritee_ushort(fio, item, n, (#item), __FILE__, __LINE__)
414 #define gmx_fio_nwrite_rvec(fio, item, n) gmx_fio_nwritee_rvec(fio, item, n, (#item), __FILE__, __LINE__)
415 #define gmx_fio_nwrite_ivec(fio, item, n) gmx_fio_nwritee_ivec(fio, item, n, (#item), __FILE__, __LINE__)
416 #define gmx_fio_nwrite_string(fio, item, n) gmx_fio_nwritee_string(fio, item, n, (#item), __FILE__, __LINE__)
418 #define gmx_fio_ndo_real(fio, item, n) gmx_fio_ndoe_real(fio, item, n, (#item), __FILE__, __LINE__)
419 #define gmx_fio_ndo_double(fio, item, n) gmx_fio_ndoe_double(fio, item, n, (#item), __FILE__, __LINE__)
420 #define gmx_fio_ndo_bool(fio, item, n) gmx_fio_ndoe_bool(fio, item, n, (#item), __FILE__, __LINE__)
421 #define gmx_fio_ndo_int(fio, item, n) gmx_fio_ndoe_int(fio, item, n, (#item), __FILE__, __LINE__)
422 #define gmx_fio_ndo_gmx_large_int(fio, item, n) gmx_fio_ndoe_gmx_large_int(fio, item, n, (#item), __FILE__, __LINE__)
423 #define gmx_fio_ndo_uchar(fio, item, n) gmx_fio_ndoe_uchar(fio, item, n, (#item), __FILE__, __LINE__)
424 #define gmx_fio_ndo_ushort(fio, item, n) gmx_fio_ndoe_ushort(fio, item, n, (#item), __FILE__, __LINE__)
425 #define gmx_fio_ndo_rvec(fio, item, n) gmx_fio_ndoe_rvec(fio, item, n, (#item), __FILE__, __LINE__)
426 #define gmx_fio_ndo_ivec(fio, item, n) gmx_fio_ndoe_ivec(fio, item, n, (#item), __FILE__, __LINE__)
427 #define gmx_fio_ndo_string(fio, item, n) gmx_fio_ndoe_string(fio, item, n, (#item), __FILE__, __LINE__)
431 #endif