2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
5 * Copyright (c) 2001-2004, The GROMACS development team.
6 * Copyright (c) 2013,2014,2015, by the GROMACS development team, led by
7 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
8 * and including many others, as listed in the AUTHORS file in the
9 * top-level source directory and at http://www.gromacs.org.
11 * GROMACS is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU Lesser General Public License
13 * as published by the Free Software Foundation; either version 2.1
14 * of the License, or (at your option) any later version.
16 * GROMACS is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * Lesser General Public License for more details.
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with GROMACS; if not, see
23 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
24 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
26 * If you want to redistribute modifications to GROMACS, please
27 * consider that scientific software is very special. Version
28 * control is crucial - bugs must be traceable. We will be happy to
29 * consider code for inclusion in the official distribution, but
30 * derived work must not be called official GROMACS. Details are found
31 * in the README & COPYING files - if they are missing, get the
32 * official version at http://www.gromacs.org.
34 * To help us fund GROMACS development, we humbly ask that you cite
35 * the research papers on the package. Check out http://www.gromacs.org.
38 #ifndef GMX_FILEIO_GMXFIO_H
39 #define GMX_FILEIO_GMXFIO_H
43 #include "gromacs/math/vectypes.h"
44 #include "gromacs/utility/cstringutil.h"
45 #include "gromacs/utility/futil.h"
46 #include "gromacs/utility/real.h"
53 /* Enumerated for data types in files */
55 eioREAL, eioFLOAT, eioDOUBLE, eioINT, eioINT64,
56 eioUCHAR, eioNUCHAR, eioUSHORT,
57 eioRVEC, eioNRVEC, eioIVEC, eioSTRING, eioNR
60 typedef struct t_fileio t_fileio;
62 /* NOTE ABOUT THREAD SAFETY:
64 The functions are all thread-safe, provided that two threads don't
65 do something silly like closing the same file, or one thread
66 accesses a file that has been closed by another.
69 /********************************************************
71 ********************************************************/
73 t_fileio *gmx_fio_open(const char *fn, const char *mode);
74 /* Open a new file for reading or writing.
75 * The file type will be deduced from the file name.
78 int gmx_fio_close(t_fileio *fp);
79 /* Close the file corresponding to fp (if not stdio)
80 * The routine will exit when an invalid fio is handled.
81 * Returns 0 on success.
84 int gmx_fio_fp_close(t_fileio *fp);
85 /* Close the file corresponding to fp without closing the FIO entry
86 * Needed e.g. for trxio because the FIO entries are used to store
88 * NOTE that the fp still needs to be properly closed with gmx_fio_close().
89 * The routine will exit when an invalid fio is handled.
90 * Returns 0 on success.
94 /* Open a file, return a stream, record the entry in internal FIO object */
95 FILE* gmx_fio_fopen(const char *fn, const char *mode);
97 /* Close a file previously opened with gmx_fio_fopen.
98 * Do not mix these calls with standard fopen/fclose ones!
99 * Returns 0 on success. */
100 int gmx_fio_fclose(FILE *fp);
104 /********************************************************
105 * Change properties of the open file
106 ********************************************************/
108 void gmx_fio_setprecision(t_fileio *fio, gmx_bool bDouble);
109 /* Select the floating point precision for reading and writing files */
111 char *gmx_fio_getname(t_fileio *fio);
112 /* Return the filename corresponding to the fio index */
114 int gmx_fio_getftp(t_fileio *fio);
115 /* Return the filetype corresponding to the fio index.
116 There is as of now no corresponding setftp function because the file
117 was opened as a specific file type and changing that midway is most
118 likely an evil hack. */
120 void gmx_fio_setdebug(t_fileio *fio, gmx_bool bDebug);
121 /* Set the debug mode */
123 gmx_bool gmx_fio_getread(t_fileio *fio);
124 /* Return whether read mode is on in fio */
127 void gmx_fio_checktype(t_fileio *fio);
128 /* Check whether the fio is of a sane type */
130 /***************************************************
132 ***************************************************/
134 void gmx_fio_rewind(t_fileio *fio);
135 /* Rewind the file in fio */
137 int gmx_fio_flush(t_fileio *fio);
138 /* Flush the fio, returns 0 on success */
140 int gmx_fio_fsync(t_fileio *fio);
141 /* fsync the fio, returns 0 on success.
142 NOTE: don't use fsync function unless you're absolutely sure you need it
143 because it deliberately interferes with the OS's caching mechanisms and
144 can cause dramatically slowed down IO performance. Some OSes (Linux,
145 for example), may implement fsync as a full sync() point. */
147 gmx_off_t gmx_fio_ftell(t_fileio *fio);
148 /* Return file position if possible */
150 int gmx_fio_seek(t_fileio *fio, gmx_off_t fpos);
151 /* Set file position if possible, quit otherwise */
153 FILE *gmx_fio_getfp(t_fileio *fio);
154 /* Return the file pointer itself */
157 /* Element with information about position in a currently open file.
158 * gmx_off_t should be defined by autoconf if your system does not have it.
159 * If you do not have it on some other platform you do not have largefile
160 * support at all, and you can define it to int (or better, find out how to
161 * enable large files). */
164 char filename[STRLEN];
166 unsigned char chksum[16];
171 int gmx_fio_get_output_file_positions(gmx_file_position_t ** outputfiles,
173 /* Return the name and file pointer positions for all currently open
174 * output files. This is used for saving in the checkpoint files, so we
175 * can truncate output files upon restart-with-appending.
177 * For the first argument you should use a pointer, which will be set to
178 * point to a list of open files.
181 t_fileio *gmx_fio_all_output_fsync(void);
182 /* fsync all open output files. This is used for checkpointing, where
183 we need to ensure that all output is actually written out to
185 This is most important in the case of some networked file systems,
186 where data is not synced with the file server until close() or
187 fsync(), so data could remain in cache for days.
188 Note the caveats reported with gmx_fio_fsync().
190 returns: NULL if no error occurred, or a pointer to the first file that
191 failed if an error occurred
195 int gmx_fio_get_file_md5(t_fileio *fio, gmx_off_t offset,
196 unsigned char digest[]);
199 int xtc_seek_time(t_fileio *fio, real time, int natoms, gmx_bool bSeekForwardOnly);
202 /********************************************************
204 ********************************************************/
207 gmx_bool gmx_fio_writee_string(t_fileio *fio, const char *item,
208 const char *desc, const char *srcfile, int line);
210 /* reading or writing, depending on the file's opening mode string */
211 gmx_bool gmx_fio_doe_real(t_fileio *fio, real *item,
212 const char *desc, const char *srcfile, int line);
213 gmx_bool gmx_fio_doe_float(t_fileio *fio, float *item,
214 const char *desc, const char *srcfile, int line);
215 gmx_bool gmx_fio_doe_double(t_fileio *fio, double *item,
216 const char *desc, const char *srcfile, int line);
217 gmx_bool gmx_fio_doe_gmx_bool(t_fileio *fio, gmx_bool *item,
218 const char *desc, const char *srcfile, int line);
219 gmx_bool gmx_fio_doe_int(t_fileio *fio, int *item,
220 const char *desc, const char *srcfile, int line);
221 gmx_bool gmx_fio_doe_int64(t_fileio *fio, gmx_int64_t *item,
222 const char *desc, const char *srcfile, int line);
223 gmx_bool gmx_fio_doe_uchar(t_fileio *fio, unsigned char *item,
224 const char *desc, const char *srcfile, int line);
225 gmx_bool gmx_fio_doe_ushort(t_fileio *fio, unsigned short *item,
226 const char *desc, const char *srcfile, int line);
227 gmx_bool gmx_fio_doe_rvec(t_fileio *fio, rvec *item,
228 const char *desc, const char *srcfile, int line);
229 gmx_bool gmx_fio_doe_ivec(t_fileio *fio, ivec *item,
230 const char *desc, const char *srcfile, int line);
231 gmx_bool gmx_fio_doe_string(t_fileio *fio, char *item,
232 const char *desc, const char *srcfile, int line);
234 /* array reading & writing */
235 gmx_bool gmx_fio_ndoe_real(t_fileio *fio, real *item, int n,
236 const char *desc, const char *srcfile, int line);
237 gmx_bool gmx_fio_ndoe_float(t_fileio *fio, float *item, int n,
238 const char *desc, const char *srcfile, int line);
239 gmx_bool gmx_fio_ndoe_double(t_fileio *fio, double *item, int n,
240 const char *desc, const char *srcfile, int line);
241 gmx_bool gmx_fio_ndoe_gmx_bool(t_fileio *fio, gmx_bool *item, int n,
242 const char *desc, const char *srcfile, int line);
243 gmx_bool gmx_fio_ndoe_int(t_fileio *fio, int *item, int n,
244 const char *desc, const char *srcfile, int line);
245 gmx_bool gmx_fio_ndoe_int64(t_fileio *fio, gmx_int64_t *item, int n,
246 const char *desc, const char *srcfile,
248 gmx_bool gmx_fio_ndoe_uchar(t_fileio *fio, unsigned char *item, int n,
249 const char *desc, const char *srcfile, int line);
250 gmx_bool gmx_fio_ndoe_ushort(t_fileio *fio, unsigned short *item, int n,
251 const char *desc, const char *srcfile, int line);
252 gmx_bool gmx_fio_ndoe_rvec(t_fileio *fio, rvec *item, int n,
253 const char *desc, const char *srcfile, int line);
254 gmx_bool gmx_fio_ndoe_ivec(t_fileio *fio, ivec *item, int n,
255 const char *desc, const char *srcfile, int line);
256 gmx_bool gmx_fio_ndoe_string(t_fileio *fio, char *item[], int n,
257 const char *desc, const char *srcfile, int line);
261 /* convenience macros */
262 #define gmx_fio_write_string(fio, item) gmx_fio_writee_string(fio, item, (#item), __FILE__, __LINE__)
264 #define gmx_fio_do_real(fio, item) gmx_fio_doe_real(fio, &item, (#item), __FILE__, __LINE__)
265 #define gmx_fio_do_float(fio, item) gmx_fio_doe_float(fio, &item, (#item), __FILE__, __LINE__)
266 #define gmx_fio_do_double(fio, item) gmx_fio_doe_double(fio, &item, (#item), __FILE__, __LINE__)
267 #define gmx_fio_do_gmx_bool(fio, item) gmx_fio_doe_gmx_bool(fio, &item, (#item), __FILE__, __LINE__)
268 #define gmx_fio_do_int(fio, item) gmx_fio_doe_int(fio, &item, (#item), __FILE__, __LINE__)
269 #define gmx_fio_do_int64(fio, item) gmx_fio_doe_int64(fio, &item, (#item), __FILE__, __LINE__)
270 #define gmx_fio_do_uchar(fio, item) gmx_fio_doe_uchar(fio, &item, (#item), __FILE__, __LINE__)
271 #define gmx_fio_do_ushort(fio, item) gmx_fio_doe_ushort(fio, &item, (#item), __FILE__, __LINE__)
272 #define gmx_fio_do_rvec(fio, item) gmx_fio_doe_rvec(fio, &item, (#item), __FILE__, __LINE__)
273 #define gmx_fio_do_ivec(fio, item) gmx_fio_doe_ivec(fio, &item, (#item), __FILE__, __LINE__)
274 #define gmx_fio_do_string(fio, item) gmx_fio_doe_string(fio, item, (#item), __FILE__, __LINE__)
277 #define gmx_fio_ndo_real(fio, item, n) gmx_fio_ndoe_real(fio, item, n, (#item), __FILE__, __LINE__)
278 #define gmx_fio_ndo_float(fio, item, n) gmx_fio_ndoe_float(fio, item, n, (#item), __FILE__, __LINE__)
279 #define gmx_fio_ndo_double(fio, item, n) gmx_fio_ndoe_double(fio, item, n, (#item), __FILE__, __LINE__)
280 #define gmx_fio_ndo_gmx_bool(fio, item, n) gmx_fio_ndoe_gmx_bool(fio, item, n, (#item), __FILE__, __LINE__)
281 #define gmx_fio_ndo_int(fio, item, n) gmx_fio_ndoe_int(fio, item, n, (#item), __FILE__, __LINE__)
282 #define gmx_fio_ndo_int64(fio, item, n) gmx_fio_ndoe_int64(fio, item, n, (#item), __FILE__, __LINE__)
283 #define gmx_fio_ndo_uchar(fio, item, n) gmx_fio_ndoe_uchar(fio, item, n, (#item), __FILE__, __LINE__)
284 #define gmx_fio_ndo_ushort(fio, item, n) gmx_fio_ndoe_ushort(fio, item, n, (#item), __FILE__, __LINE__)
285 #define gmx_fio_ndo_rvec(fio, item, n) gmx_fio_ndoe_rvec(fio, item, n, (#item), __FILE__, __LINE__)
286 #define gmx_fio_ndo_ivec(fio, item, n) gmx_fio_ndoe_ivec(fio, item, n, (#item), __FILE__, __LINE__)
287 #define gmx_fio_ndo_string(fio, item, n) gmx_fio_ndoe_string(fio, item, n, (#item), __FILE__, __LINE__)