src/gromacs/fileio/gmxfio.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   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,2018,2019, 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.
  10  *
  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.
  15  *
  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.
  20  *
  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.
  25  *
  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.
  33  *
  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.
  36  */
  37
  38 #ifndef GMX_FILEIO_GMXFIO_H
  39 #define GMX_FILEIO_GMXFIO_H
  40
  41 #include <stdio.h>
  42
  43 #include <array>
  44 #include <vector>
  45
  46 #include "gromacs/math/vectypes.h"
  47 #include "gromacs/utility/cstringutil.h"
  48 #include "gromacs/utility/futil.h"
  49 #include "gromacs/utility/real.h"
  50
  51 typedef struct t_fileio t_fileio;
  52
  53 /* NOTE ABOUT THREAD SAFETY:
  54
  55    The functions are all thread-safe, provided that two threads don't
  56    do something silly like closing the same file, or one thread
  57    accesses a file that has been closed by another.
  58  */
  59
  60 /********************************************************
  61  * Open and Close
  62  ********************************************************/
  63
  64 t_fileio* gmx_fio_open(const char* fn, const char* mode);
  65 /* Open a new file for reading or writing.
  66  * The file type will be deduced from the file name.
  67  */
  68
  69 int gmx_fio_close(t_fileio* fp);
  70 /* Close the file corresponding to fp (if not stdio)
  71  * The routine will exit when an invalid fio is handled.
  72  * Returns 0 on success.
  73  */
  74
  75 int gmx_fio_fp_close(t_fileio* fp);
  76 /* Close the file corresponding to fp without closing the FIO entry
  77  * Needed e.g. for trxio because the FIO entries are used to store
  78  * additional data.
  79  * NOTE that the fp still needs to be properly closed with gmx_fio_close().
  80  * The routine will exit when an invalid fio is handled.
  81  * Returns 0 on success.
  82  */
  83
  84
  85 /* Open a file, return a stream, record the entry in internal FIO object */
  86 FILE* gmx_fio_fopen(const char* fn, const char* mode);
  87
  88 /* Close a file previously opened with gmx_fio_fopen.
  89  * Do not mix these calls with standard fopen/fclose ones!
  90  * Returns 0 on success.  */
  91 int gmx_fio_fclose(FILE* fp);
  92
  93
  94 /********************************************************
  95  * Change properties of the open file
  96  ********************************************************/
  97
  98 char* gmx_fio_getname(t_fileio* fio);
  99 /* Return the filename corresponding to the fio index */
 100
 101 int gmx_fio_getftp(t_fileio* fio);
 102 /* Return the filetype corresponding to the fio index.
 103     There is as of now no corresponding setftp function because the file
 104     was opened as a specific file type and changing that midway is most
 105     likely an evil hack. */
 106
 107 gmx_bool gmx_fio_getread(t_fileio* fio);
 108 /* Return  whether read mode is on in fio  */
 109
 110 /***************************************************
 111  * FILE Operations
 112  ***************************************************/
 113
 114 void gmx_fio_rewind(t_fileio* fio);
 115 /* Rewind the file in fio */
 116
 117 int gmx_fio_flush(t_fileio* fio);
 118 /* Flush the fio, returns 0 on success */
 119
 120 int gmx_fio_fsync(t_fileio* fio);
 121 /* fsync the fio, returns 0 on success.
 122    NOTE: don't use fsync function unless you're absolutely sure you need it
 123    because it deliberately interferes with the OS's caching mechanisms and
 124    can cause dramatically slowed down IO performance. Some OSes (Linux,
 125    for example), may implement fsync as a full sync() point. */
 126
 127 gmx_off_t gmx_fio_ftell(t_fileio* fio);
 128 /* Return file position if possible */
 129
 130 int gmx_fio_seek(t_fileio* fio, gmx_off_t fpos);
 131 /* Set file position if possible, quit otherwise */
 132
 133 FILE* gmx_fio_getfp(t_fileio* fio);
 134 /* Return the file pointer itself */
 135
 136
 137 /* Element with information about position in a currently open file.
 138  * gmx_off_t should be defined by autoconf if your system does not have it.
 139  * If you do not have it on some other platform you do not have largefile
 140  * support at all, and you can define it to int (or better, find out how to
 141  * enable large files).  */
 142 struct gmx_file_position_t
 143 {
 144     char                          filename[STRLEN] = { 0 };
 145     gmx_off_t                     offset           = 0;
 146     std::array<unsigned char, 16> checksum         = { { 0 } };
 147     int                           checksumSize     = 0;
 148 };
 149
 150 /*! \brief Return data about output files.
 151  *
 152  * This is used for handling data stored in the checkpoint files, so
 153  * we can truncate output files upon restart-with-appending. */
 154 std::vector<gmx_file_position_t> gmx_fio_get_output_file_positions();
 155
 156 t_fileio* gmx_fio_all_output_fsync();
 157 /* fsync all open output files. This is used for checkpointing, where
 158    we need to ensure that all output is actually written out to
 159    disk.
 160    This is most important in the case of some networked file systems,
 161    where data is not synced with the file server until close() or
 162    fsync(), so data could remain in cache for days.
 163    Note the caveats reported with gmx_fio_fsync().
 164
 165     returns: NULL if no error occurred, or a pointer to the first file that
 166              failed if an error occurred
 167  */
 168
 169
 170 int gmx_fio_get_file_md5(t_fileio* fio, gmx_off_t offset, std::array<unsigned char, 16>* checksum);
 171
 172
 173 int xtc_seek_time(t_fileio* fio, real time, int natoms, gmx_bool bSeekForwardOnly);
 174
 175
 176 #endif