8.3
general documentation
cs_file.h
Go to the documentation of this file.
1#ifndef __CS_FILE_H__
2#define __CS_FILE_H__
3
4/*============================================================================
5 * File and directory operations, with parallel file I/O
6 *============================================================================*/
7
8/*
9 This file is part of code_saturne, a general-purpose CFD tool.
10
11 Copyright (C) 1998-2024 EDF S.A.
12
13 This program is free software; you can redistribute it and/or modify it under
14 the terms of the GNU General Public License as published by the Free Software
15 Foundation; either version 2 of the License, or (at your option) any later
16 version.
17
18 This program is distributed in the hope that it will be useful, but WITHOUT
19 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21 details.
22
23 You should have received a copy of the GNU General Public License along with
24 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25 Street, Fifth Floor, Boston, MA 02110-1301, USA.
26*/
27
28/*----------------------------------------------------------------------------*/
29
30#if defined(HAVE_MPI)
31#include <mpi.h>
32#endif
33
34/*----------------------------------------------------------------------------
35 * Local headers
36 *----------------------------------------------------------------------------*/
37
38#include "cs_defs.h"
39
40/*----------------------------------------------------------------------------*/
41
43
44/*=============================================================================
45 * Macro definitions
46 *============================================================================*/
47
48/*============================================================================
49 * Type definitions
50 *============================================================================*/
51
52/* File descriptor */
53
54typedef struct _cs_file_t cs_file_t;
55
56/* Helper structure for IO serialization */
57
58#if defined(HAVE_MPI)
59typedef struct _cs_file_serializer_t cs_file_serializer_t;
60#endif
61
62/* File modes */
63
64typedef enum {
65
66 CS_FILE_MODE_READ, /* Read mode */
67 CS_FILE_MODE_WRITE, /* Write mode */
68 CS_FILE_MODE_APPEND /* Append mode */
69
71
72/* Possibilities for the third argument of cs_file_seek() */
73
74typedef enum {
75
76 CS_FILE_SEEK_SET, /* Seek from beginning of file */
77 CS_FILE_SEEK_CUR, /* Seek from current position */
78 CS_FILE_SEEK_END /* Seek from end of file */
79
81
82/* File access methods */
83
84typedef enum {
85
93
95
96/* MPI-IO file positioning methods */
97
98typedef enum {
99
102
104
105/* Offset for file position indicator (int64_t in C99) */
106
107#if defined(SIZEOF_LONG_LONG)
108typedef long long cs_file_off_t;
109#else
110typedef long cs_file_off_t;
111#endif
112
113/*=============================================================================
114 * Global variables
115 *============================================================================*/
116
117/* names associated with file access methods */
118
119extern const char *cs_file_access_name[];
120
121/* names associated with MPI-IO positioning */
122
123extern const char *cs_file_mpi_positioning_name[];
124
125/*=============================================================================
126 * Public function prototypes
127 *============================================================================*/
128
129/*----------------------------------------------------------------------------
130 * Create a file descriptor and open the associated file.
131 *
132 * By default, data is written or read as native data. This behavior may be
133 * modified by cs_file_set_swap_endian().
134 *
135 * parameters:
136 * name <-- file name
137 * mode <-- file access mode: read, write, or append
138 * method <-- file access method
139 * hints <-- associated hints for MPI-IO, or MPI_INFO_NULL
140 * block_comm <-- handle to MPI communicator used for distributed file
141 * block access (may be a subset of comm if some ranks do
142 * not directly access distributed data blocks)
143 * comm <-- handle to main MPI communicator
144 *
145 * returns:
146 * pointer to cs_file_t file descriptor (NULL in case of failure);
147 * currently, errors are fatal.
148 *----------------------------------------------------------------------------*/
149
150#if defined(HAVE_MPI)
151
152cs_file_t *
153cs_file_open(const char *name,
154 cs_file_mode_t mode,
155 cs_file_access_t method,
156 MPI_Info hints,
157 MPI_Comm block_comm,
158 MPI_Comm comm);
159
160#else
161
162cs_file_t *
163cs_file_open(const char *name,
164 cs_file_mode_t mode,
165 cs_file_access_t method);
166
167#endif
168
169/*----------------------------------------------------------------------------
170 * Create a file descriptor and open the associated file, using the default
171 * file communicator and access method.
172 *
173 * By default, data is written or read as native data. This behavior may be
174 * modified by cs_file_set_swap_endian().
175 *
176 * parameters:
177 * name <-- file name
178 * mode <-- file access mode: read, write, or append
179 *
180 * returns:
181 * pointer to cs_file_t file descriptor (NULL in case of failure);
182 * currently, errors are fatal.
183 *----------------------------------------------------------------------------*/
184
185cs_file_t *
186cs_file_open_default(const char *name,
187 cs_file_mode_t mode);
188
189/*----------------------------------------------------------------------------*/
203/*----------------------------------------------------------------------------*/
204
205cs_file_t *
206cs_file_open_serial(const char *name,
207 cs_file_mode_t mode);
208
209/*----------------------------------------------------------------------------
210 * Destroy a file descriptor and close the associated file.
211 *
212 * parameters:
213 * f <-> file descriptor to destroy
214 *
215 * returns:
216 * null pointer
217 *----------------------------------------------------------------------------*/
218
219cs_file_t *
221
222/*----------------------------------------------------------------------------*/
223/*
224 * \brief Transfer a block of data to file in memory.
225 *
226 * Only for files opened using CS_FILE_IN_MEMORY_SERIAL.
227 *
228 * \param[in] f cs_file_t descriptor
229 * \param[in] nb number of matching bytes for data
230 * \param[in] data data buffer (ownership is relinquished by caller)
231 */
232/*----------------------------------------------------------------------------*/
233
234void
236 size_t nb,
237 void *data);
238
239/*----------------------------------------------------------------------------
240 * Return a file's name.
241 *
242 * parameters:
243 * f <-- cs_file_t descriptor
244 *
245 * returns:
246 * pointer to the file's name.
247 *----------------------------------------------------------------------------*/
248
249const char *
251
252/*----------------------------------------------------------------------------
253 * Get pointer to data for file in memory.
254 *
255 * parameters:
256 * f <-- cs_file_t descriptor
257 *
258 * return:
259 * pointer to file data.
260 *----------------------------------------------------------------------------*/
261
262void *
264
265/*----------------------------------------------------------------------------
266 * Allow global read attemps past end of file without throwing an error.
267 *
268 * Currently only for files with serial access.
269 *
270 * parameters:
271 * f <-> cs_file_t descriptor
272 * allow_eof <-- allow read attempt pas EOF
273 *----------------------------------------------------------------------------*/
274
275void
277 bool allow_eof);
278
279/*----------------------------------------------------------------------------
280 * Ensure that data is read or written in big-endian
281 * (network standard) format.
282 *
283 * parameters:
284 * f <-> cs_file_t descriptor
285 *----------------------------------------------------------------------------*/
286
287void
289
290/*----------------------------------------------------------------------------
291 * Return a file's byte-swapping behavior.
292 *
293 * parameters:
294 * f <-- cs_file_t descriptor
295 *
296 * returns:
297 * 0 if file's endianness is the same as the system's, 1 otherwise.
298 *----------------------------------------------------------------------------*/
299
300int
302
303/*----------------------------------------------------------------------------
304 * Set a file's byte-swapping behavior.
305 *
306 * Using this function assumes one is familiar with a file's coding
307 * or structure; use with caution.
308 *
309 * parameters:
310 * f <-> cs_file_t descriptor
311 * swap <-- 1 if bytes must be swapped, 0 otherwise
312 *----------------------------------------------------------------------------*/
313
314void
316 int swap);
317
318/*----------------------------------------------------------------------------
319 * Read global data from a file, distributing it to all processes
320 * associated with that file.
321 *
322 * parameters:
323 * f <-- cs_file_t descriptor
324 * buf --> pointer to location receiving data
325 * size <-- size of each item of data in bytes
326 * ni <-- number of items to read
327 *
328 * returns:
329 * the number of items (not bytes) sucessfully read; currently,
330 * errors are fatal.
331 *----------------------------------------------------------------------------*/
332
333size_t
335 void *buf,
336 size_t size,
337 size_t ni);
338
339/*----------------------------------------------------------------------------
340 * Write global data to a file.
341 *
342 * Under MPI, data is only written by the associated communicator's root
343 * rank. The buffers on other ranks are ignored, though the file offset
344 * is updated (i.e. the call to this function is collective).
345 *
346 * parameters:
347 * f <-- cs_file_t descriptor
348 * buf <-- pointer to location containing data
349 * size <-- size of each item of data in bytes
350 * ni <-- number of items to read
351 *
352 * returns:
353 * the number of items (not bytes) sucessfully written; currently,
354 * errors are fatal.
355 *----------------------------------------------------------------------------*/
356
357size_t
359 const void *buf,
360 size_t size,
361 size_t ni);
362
363/*----------------------------------------------------------------------------
364 * Read data to a buffer, distributing a contiguous part of it to each
365 * process associated with a file.
366 *
367 * Each process should receive a (possibly empty) block of the data,
368 * and we should have:
369 * global_num_start at rank 0 = 1
370 * global_num_start at rank i+1 = global_num_end at rank i.
371 * Otherwise, behavior (especially positioning for future reads) is undefined.
372 *
373 * parameters:
374 * f <-- cs_file_t descriptor
375 * buf --> pointer to location receiving data
376 * size <-- size of each item of data in bytes
377 * stride <-- number of (interlaced) values per block item
378 * global_num_start <-- global number of first block item (1 to n numbering)
379 * global_num_end <-- global number of past-the end block item
380 * (1 to n numbering)
381 *
382 * returns:
383 * the (local) number of items (not bytes) sucessfully read; currently,
384 * errors are fatal.
385 *----------------------------------------------------------------------------*/
386
387size_t
389 void *buf,
390 size_t size,
391 size_t stride,
392 cs_gnum_t global_num_start,
393 cs_gnum_t global_num_end);
394
395/*----------------------------------------------------------------------------
396 * Write data to a file, each associated process providing a contiguous part
397 * of this data.
398 *
399 * Each process should provide a (possibly empty) block of the data,
400 * and we should have:
401 * global_num_start at rank 0 = 1
402 * global_num_start at rank i+1 = global_num_end at rank i.
403 * Otherwise, behavior (especially positioning for future reads) is undefined.
404 *
405 * This function may require an internal copy of the data to ensure that
406 * the buffer contents are not modified, so if the buffer contents are
407 * temporary values, to be deleted after writing, using
408 * cs_file_write_block_buffer() instead may be used to avoid an unneeded
409 * memory allocation and copy.
410 *
411 * parameters:
412 * f <-- cs_file_t descriptor
413 * buf <-- pointer to location containing data
414 * size <-- size of each item of data in bytes
415 * stride <-- number of (interlaced) values per block item
416 * global_num_start <-- global number of first block item (1 to n numbering)
417 * global_num_end <-- global number of past-the end block item
418 * (1 to n numbering)
419 *
420 * returns:
421 * the (local) number of items (not bytes) sucessfully written; currently,
422 * errors are fatal.
423 *----------------------------------------------------------------------------*/
424
425size_t
427 const void *buf,
428 size_t size,
429 size_t stride,
430 cs_gnum_t global_num_start,
431 cs_gnum_t global_num_end);
432
433/*----------------------------------------------------------------------------
434 * Write data to a file, each associated process providing a contiguous part
435 * of this data.
436 *
437 * Each process should provide a (possibly empty) block of the data,
438 * and we should have:
439 * global_num_start at rank 0 = 1
440 * global_num_start at rank i+1 = global_num_end at rank i.
441 * Otherwise, behavior (especially positioning for future reads) is undefined.
442 *
443 * This function is intended to be used mainly data that is already a
444 * copy of original data (such as data that has been redistributed across
445 * processors just for the sake of output), or that is to be deleted after
446 * writing, so it may modify the values in its input buffer (notably to
447 * convert from little-endian to big-endian of vice-versa if necessary).
448 *
449 * parameters:
450 * f <-- cs_file_t descriptor
451 * buf <-> pointer to location containing data
452 * size <-- size of each item of data in bytes
453 * stride <-- number of (interlaced) values per block item
454 * global_num_start <-- global number of first block item (1 to n numbering)
455 * global_num_end <-- global number of past-the end block item
456 * (1 to n numbering)
457 *
458 * returns:
459 * the (local) number of items (not bytes) sucessfully written; currently,
460 * errors are fatal.
461 *----------------------------------------------------------------------------*/
462
463size_t
465 void *buf,
466 size_t size,
467 size_t stride,
468 cs_gnum_t global_num_start,
469 cs_gnum_t global_num_end);
470
471/*----------------------------------------------------------------------------
472 * Update the file pointer according to whence.
473 *
474 * parameters:
475 * f <-> cs_file_t descriptor.
476 * offset <-- add to position specified to whence to obtain new position,
477 * measured in characters from the beginning of the file.
478 * whence <-- beginning if CS_FILE_SEEK_SET, current if CS_FILE_SEEK_CUR,
479 * or end-of-file if CS_FILE_SEEK_END.
480 *
481 * returns:
482 * 0 upon success, nonzero otherwise; currently, errors are fatal.
483 *----------------------------------------------------------------------------*/
484
485int
487 cs_file_off_t offset,
488 cs_file_seek_t whence);
489
490/*----------------------------------------------------------------------------
491 * Return the position of the file pointer.
492 *
493 * In parallel, we consider the file pointer to be equal to the highest
494 * value of the individual file pointers.
495 *
496 * parameters:
497 * f <-- cs_file_t descriptor
498 *
499 * returns:
500 * current position of the file pointer
501 *----------------------------------------------------------------------------*/
502
505
506/*----------------------------------------------------------------------------*/
518/*----------------------------------------------------------------------------*/
519
520char *
521cs_file_gets(char *s,
522 const int size,
523 const cs_file_t *f,
524 int *line);
525
526/*----------------------------------------------------------------------------*/
543/*----------------------------------------------------------------------------*/
544
545char *
546cs_file_gets_try(char *s,
547 const int size,
548 const cs_file_t *f,
549 int *line);
550
551/*----------------------------------------------------------------------------
552 * Dump the metadata of a file structure in human readable form
553 *
554 * parameters:
555 * f <-- pointer to file
556 *----------------------------------------------------------------------------*/
557
558void
559cs_file_dump(const cs_file_t *f);
560
561/*----------------------------------------------------------------------------
562 * Free the default options for file access.
563 *----------------------------------------------------------------------------*/
564
565void
567
568/*----------------------------------------------------------------------------
569 * Get the default options for file access.
570 *
571 * parameters:
572 * mode <-- file mode for which the default is queried (write and
573 * append use the same method, and are interchangeable here)
574 * access --> default file access method, or null
575 * hints --> MPI-IO hints, or null
576 *----------------------------------------------------------------------------*/
577
578#if defined(HAVE_MPI)
579
580void
582 cs_file_access_t *method,
583 MPI_Info *hints);
584
585#else
586
587void
589 cs_file_access_t *method);
590
591#endif
592
593/*----------------------------------------------------------------------------
594 * Set the default options for file access.
595 *
596 * If the method given contains incompatible values, such as when setting
597 * MPI-IO methods when MPI-IO is not available, a "reasonable" default
598 * is used instead.
599 *
600 * parameters:
601 * mode <-- file mode for which the default is to be set (write and
602 * append use the same method, and are interchangeable here)
603 * method <-- default access method to set
604 * hints <-- MPI-IO hints, or MPI_INFO_NULL
605 *----------------------------------------------------------------------------*/
606
607#if defined(HAVE_MPI)
608
609void
611 cs_file_access_t method,
612 MPI_Info hints);
613
614#else
615
616void
618 cs_file_access_t method);
619
620#endif
621
622#if defined(HAVE_MPI)
623
624/*----------------------------------------------------------------------------
625 * Get default MPI communicator values for file access.
626 *
627 * A block rank stepping value may be used, allowing the use of a reduced
628 * communicator for distributed block reads and writes.
629 * If this value is greater than 1, ranks not a multiple of this step must be
630 * guaranteed to be empty for block reads and writes with files opened using
631 * this default.
632 *
633 * parameters:
634 * block_rank_step --> MPI rank stepping between non-empty distributed blocks,
635 * or null
636 * block_comm --> Handle to MPI communicator used for distributed
637 * file block access, or null
638 * comm --> Handle to main MPI communicator, or null
639 *----------------------------------------------------------------------------*/
640
641void
642cs_file_get_default_comm(int *block_rank_step,
643 MPI_Comm *block_comm,
644 MPI_Comm *comm);
645
646/*----------------------------------------------------------------------------
647 * Set default MPI communicator values for file access.
648 *
649 * A block rank stepping value may be used, allowing the use of a reduced
650 * communicator for distributed block reads and writes.
651 * If this value is greater than 1, ranks not a multiple of this step must be
652 * guaranteed to be empty for block reads and writes with files opened using
653 * this default.
654 *
655 * For each argument, an "out of range" value may be used to avoid modifying
656 * the previous default for that argument.
657 *
658 * parameters:
659 * block_rank_step <-- MPI rank stepping between non-empty blocks for
660 * file block reads and writes (not set if <= 0)
661 * comm <-- handle to main MPI communicator
662 * (not set if MPI_COMM_SELF)
663 *----------------------------------------------------------------------------*/
664
665void
666cs_file_set_default_comm(int block_rank_step,
667 MPI_Comm comm);
668
669/*----------------------------------------------------------------------------
670 * Create an MPI communicator for distributed block parallel IO.
671 *
672 * parameters:
673 * block_rank_step <-- MPI rank stepping between non-empty blocks
674 * comm <-- Handle to main MPI communicator
675 *
676 * returns:
677 * communicator associated with IO, MPI_COMM_NULL for ranks not
678 * participating in parallel IO (including ranks participating in IO
679 * where communicator size would be 1)
680 *----------------------------------------------------------------------------*/
681
682MPI_Comm
683cs_file_block_comm(int block_rank_step,
684 MPI_Comm comm);
685
686#endif /* defined(HAVE_MPI) */
687
688/*----------------------------------------------------------------------------
689 * Get the positioning method for MPI-IO
690 *
691 * For details, see cs_file_set_mpi_io_positioning().
692 *
693 * returns:
694 * positioning method for MPI-IO
695 *----------------------------------------------------------------------------*/
696
699
700/*----------------------------------------------------------------------------
701 * Set the positioning method for MPI-IO
702 *
703 * It is not always known whether a performance or robustness difference is
704 * to be expected using explicit file offsets or individual file pointers.
705 * Perusal of a sampling of ROMIO code would seem to indicate that no
706 * difference is to be expected, but this might change with MPI IO variants
707 * or file systems, so this advanced setting is made possible.
708 *
709 * This setting is not available on a per-file basis, though this could be
710 * done in the future in the unexpected case of performance results
711 * showing this would be useful.
712 *
713 * parameters:
714 * positioning <-- chosen positioning method for MPI-IO
715 *----------------------------------------------------------------------------*/
716
717void
719
720/*----------------------------------------------------------------------------
721 * Print information on default options for file access.
722 *----------------------------------------------------------------------------*/
723
724void
726
727#if defined(HAVE_MPI)
728
729/*----------------------------------------------------------------------------
730 * Create a cs_file_serializer_t structure.
731 *
732 * The buf_block_size argument is optional, and may be used when the buffer
733 * on rank 0 is larger than (global_num_end - global_num_start)*size*stride
734 * bytes. If zero, a block size of (global_num_end - global_num_start) on
735 * rank 0 is assumed; a buffer may not be smaller than this, as it must
736 * initially contain all data on rank 0's block.
737 *
738 * parameters:
739 * size <-- size of each item of data in bytes
740 * stride <-- number of (interlaced) values per block item
741 * global_num_start <-- global number of first block item (1 to n numbering)
742 * global_num_end <-- global number of past-the end block item
743 * (1 to n numbering)
744 * buf_block_size <-- Local data buffer block size, or 0 for default
745 * global_num_end - global_num_start
746 * (only useful on rank 0)
747 * buf <-- pointer to local block data buffer
748 * comm <-- associated MPI communicator
749 *
750 * returns:
751 * pointer to new serializer structure
752 *----------------------------------------------------------------------------*/
753
755cs_file_serializer_create(size_t size,
756 size_t stride,
757 cs_gnum_t global_num_start,
758 cs_gnum_t global_num_end,
759 size_t buf_block_size,
760 void *buf,
761 MPI_Comm comm);
762
763/*----------------------------------------------------------------------------
764 * Destroy a cs_file_serializer_t structure.
765 *
766 * parameters:
767 * s <-> pointer to pointer structure that should be destroyed
768 *----------------------------------------------------------------------------*/
769
770void
772
773/*----------------------------------------------------------------------------
774 * Advance a cs_file_serializer_t structure.
775 *
776 * Data from the buffer of the next communicating rank is copied
777 * to rank 0 (this is a no-op the first time this function is called,
778 * as rank 0 already has its data).
779 *
780 * On rank 0, the return value may point to the buffer defined when
781 * initializing the serializer, or to an aditional buffer if the former is
782 * too small to receive data from all ranks.
783 *
784 * Note also that for ranks > 0, this function always returns null,
785 * as only one call is needed for those ranks.
786 *
787 * parameters:
788 * s <-- pointer to serializer structure
789 * cur_range --> optional start and past-the end global numbers for the
790 * current block (size: 2), or null; only on rank 0
791 *
792 * returns:
793 * a pointer to the buffer containing new data (first call counts as new),
794 * or null if we are finished; always null on ranks > 0
795 *----------------------------------------------------------------------------*/
796
797void *
799 cs_gnum_t cur_range[2]);
800
801#endif /* defined(HAVE_MPI) */
802
803/*----------------------------------------------------------------------------
804 * Create a new directory using default permissions.
805 *
806 * This function is similar to the POSIX function mkdir(), except that
807 * it has no "mode" argument: by default, on a POSIX type system,
808 * permissions include read, write, and execute access for the user,
809 * group and others, modified by the users umask value (so with a
810 * typical configuration, the user will have read, write, and execute
811 * pemission, the group and others will only have read and execute
812 * permission, but this behavior may be modified).
813 *
814 * Also, contrary to the usual mkdir(), if the directory already
815 * exists (and is truly a directory), this is considered a success
816 * and not a failure, and 0 is returned: the aim of this function
817 * is to make a directory available, so if it already exists,
818 * this is considered acceptable.
819 *
820 * parameters:
821 * path: <-- name of new directory.
822 *
823 * returns:
824 * 0 on success, -1 if an error occured (in which case errno
825 * contains the appropriate error code). If the underlying
826 * system has no mkdir() function or it was not detected
827 * upon BFT configuration, 1 is returned.
828 *----------------------------------------------------------------------------*/
829
830int
831cs_file_mkdir_default(const char *path);
832
833/*----------------------------------------------------------------------------
834 * Check if a file exists and is a regular file.
835 *
836 * parameters:
837 * path <-- file name.
838 *
839 * returns:
840 * 1 if file exists and is a regular file, 0 otherwise.
841 *----------------------------------------------------------------------------*/
842
843int
844cs_file_isreg(const char *path);
845
846/*----------------------------------------------------------------------------
847 * Check if a directory exists.
848 *
849 * parameters:
850 * path <-- directory name.
851 *
852 * returns:
853 * 1 if directory exists, 0 otherwise.
854 *----------------------------------------------------------------------------*/
855
856int
857cs_file_isdir(const char *path);
858
859/*----------------------------------------------------------------------------
860 * List files inside a directory.
861 *
862 * The array returned must be freed by the caller using BFT_FREE,
863 * as well as the individual entries in the array.
864 *
865 * parameters:
866 * path <-- name of directory.
867 *
868 * returns:
869 * an array of file names in a directory. The last entry is set to null.
870 * If no means to list the directory or an error occured, the return
871 * value is simply null.
872 *----------------------------------------------------------------------------*/
873
874char **
875cs_file_listdir(const char *path);
876
877/*----------------------------------------------------------------------------
878 * Return the size of a file.
879 *
880 * If the file does not exist, 0 is returned.
881 *
882 * Note that for some special files, such as files in the Linux /proc
883 * directory, this may return 0.
884 *
885 * parameters
886 * path <-- file path.
887 *
888 * returns:
889 * size of file.
890 *----------------------------------------------------------------------------*/
891
893cs_file_size(const char *path);
894
895/*----------------------------------------------------------------------------
896 * Remove a file if it exists and is a regular file or an empty directory.
897 *
898 * parameters
899 * path <-- file path.
900 *
901 * returns:
902 * 0 in case of success or if file does not exist, not 0 otherwise.
903 *----------------------------------------------------------------------------*/
904
905int
906cs_file_remove(const char *path);
907
908/*----------------------------------------------------------------------------
909 * Check if a file name ends with a specific string (extension)
910 *
911 * parameters
912 * path <-- file path.
913 * end <-- string to compare
914 *
915 * returns:
916 * 1 if the path ends with the given string, 0 otherwise.
917 *----------------------------------------------------------------------------*/
918
919int
920cs_file_endswith(const char *path,
921 const char *end);
922
923/*----------------------------------------------------------------------------*/
924
926
927#endif /* __CS_FILE_H__ */
#define BEGIN_C_DECLS
Definition: cs_defs.h:542
uint64_t cs_gnum_t
global mesh entity number
Definition: cs_defs.h:325
#define MPI_Info
Definition: cs_defs.h:94
#define END_C_DECLS
Definition: cs_defs.h:543
void cs_file_dump(const cs_file_t *f)
Dump the metadata of a file structure in human readable form.
Definition: cs_file.cpp:3776
cs_file_off_t cs_file_tell(cs_file_t *f)
Return the position of the file pointer.
Definition: cs_file.cpp:3682
int cs_file_get_swap_endian(const cs_file_t *f)
Return a file's byte-swapping behavior.
Definition: cs_file.cpp:2934
void cs_file_get_default_access(cs_file_mode_t mode, cs_file_access_t *method, MPI_Info *hints)
Get the default options for file access.
Definition: cs_file.cpp:3888
const char * cs_file_mpi_positioning_name[]
Definition: cs_file.cpp:348
void cs_file_serializer_destroy(cs_file_serializer_t **s)
Destroy a cs_file_serializer_t structure.
Definition: cs_file.cpp:4390
void cs_file_set_default_comm(int block_rank_step, MPI_Comm comm)
Set default MPI communicator values for file access.
Definition: cs_file.cpp:4095
const char * cs_file_get_name(const cs_file_t *f)
Return a file's name.
Definition: cs_file.cpp:2883
struct _cs_file_serializer_t cs_file_serializer_t
Definition: cs_file.h:59
cs_file_t * cs_file_open(const char *name, cs_file_mode_t mode, cs_file_access_t method, MPI_Info hints, MPI_Comm block_comm, MPI_Comm comm)
Create a file descriptor and open the associated file.
Definition: cs_file.cpp:2551
cs_file_serializer_t * cs_file_serializer_create(size_t size, size_t stride, cs_gnum_t global_num_start, cs_gnum_t global_num_end, size_t buf_block_size, void *buf, MPI_Comm comm)
Create a cs_file_serializer_t structure.
Definition: cs_file.cpp:4358
int cs_file_isdir(const char *path)
Check if a directory exists.
Definition: cs_file.cpp:4676
void * cs_file_in_memory_get_data(cs_file_t *f)
Get pointer to data for file in memory.
Definition: cs_file.cpp:2822
long long cs_file_off_t
Definition: cs_file.h:108
void cs_file_get_default_comm(int *block_rank_step, MPI_Comm *block_comm, MPI_Comm *comm)
Get default MPI communicator values for file access.
Definition: cs_file.cpp:4043
size_t cs_file_write_global(cs_file_t *f, const void *buf, size_t size, size_t ni)
Write global data to a file.
Definition: cs_file.cpp:3076
cs_file_t * cs_file_free(cs_file_t *f)
Destroy a file descriptor and close the associated file.
Definition: cs_file.cpp:2789
cs_file_t * cs_file_open_default(const char *name, cs_file_mode_t mode)
Create a file descriptor and open the associated file, using the default file communicator and access...
Definition: cs_file.cpp:2705
char * cs_file_gets_try(char *s, const int size, const cs_file_t *f, int *line)
Formatted input from a text file if possible (as fgets()).
Definition: cs_file.cpp:3759
cs_file_access_t
Definition: cs_file.h:84
@ CS_FILE_MPI_INDEPENDENT
Definition: cs_file.h:89
@ CS_FILE_IN_MEMORY_SERIAL
Definition: cs_file.h:92
@ CS_FILE_MPI_COLLECTIVE
Definition: cs_file.h:91
@ CS_FILE_MPI_NON_COLLECTIVE
Definition: cs_file.h:90
@ CS_FILE_STDIO_SERIAL
Definition: cs_file.h:87
@ CS_FILE_STDIO_PARALLEL
Definition: cs_file.h:88
@ CS_FILE_DEFAULT
Definition: cs_file.h:86
size_t cs_file_read_block(cs_file_t *f, void *buf, size_t size, size_t stride, cs_gnum_t global_num_start, cs_gnum_t global_num_end)
Read data to a buffer, distributing a contiguous part of it to each process associated with a file.
Definition: cs_file.cpp:3211
void cs_file_free_defaults(void)
Free the default options for file access.
Definition: cs_file.cpp:3843
void cs_file_set_big_endian(cs_file_t *f)
Ensure that data is read or written in big-endian (network standard) format.
Definition: cs_file.cpp:2900
struct _cs_file_t cs_file_t
Definition: cs_file.h:54
size_t cs_file_write_block_buffer(cs_file_t *f, void *buf, size_t size, size_t stride, cs_gnum_t global_num_start, cs_gnum_t global_num_end)
Write data to a file, each associated process providing a contiguous part of this data.
Definition: cs_file.cpp:3460
cs_file_off_t cs_file_size(const char *path)
Return the size of a file.
Definition: cs_file.cpp:4782
int cs_file_remove(const char *path)
Remove a file if it exists and is a regular file or an empty directory.
Definition: cs_file.cpp:4835
int cs_file_seek(cs_file_t *f, cs_file_off_t offset, cs_file_seek_t whence)
Update the file pointer according to whence.
Definition: cs_file.cpp:3593
int cs_file_endswith(const char *path, const char *end)
Check if file name/path ends with a specific string.
Definition: cs_file.cpp:4903
int cs_file_isreg(const char *path)
Check if a file exists and is a regular file.
Definition: cs_file.cpp:4630
void cs_file_in_memory_transfer_data(cs_file_t *f, size_t nb, void *data)
Transfer a block of data to file in memory.
Definition: cs_file.cpp:2859
void cs_file_set_mpi_io_positioning(cs_file_mpi_positioning_t positioning)
Set the positioning method for MPI-IO.
Definition: cs_file.cpp:4239
void cs_file_defaults_info(void)
Print information on default options for file access.
Definition: cs_file.cpp:4251
cs_file_mode_t
Definition: cs_file.h:64
@ CS_FILE_MODE_APPEND
Definition: cs_file.h:68
@ CS_FILE_MODE_WRITE
Definition: cs_file.h:67
@ CS_FILE_MODE_READ
Definition: cs_file.h:66
size_t cs_file_read_global(cs_file_t *f, void *buf, size_t size, size_t ni)
Read global data from a file, distributing it to all processes associated with that file.
Definition: cs_file.cpp:2975
MPI_Comm cs_file_block_comm(int block_rank_step, MPI_Comm comm)
Create an MPI communicator for distributed block parallel IO.
Definition: cs_file.cpp:4149
char ** cs_file_listdir(const char *path)
List files inside a directory.
Definition: cs_file.cpp:4723
void cs_file_set_default_access(cs_file_mode_t mode, cs_file_access_t method, MPI_Info hints)
Set the default options for file access.
Definition: cs_file.cpp:3954
char * cs_file_gets(char *s, const int size, const cs_file_t *f, int *line)
Formatted input from a text file (as fgets()).
Definition: cs_file.cpp:3731
int cs_file_mkdir_default(const char *path)
Create a new directory using default permissions.
Definition: cs_file.cpp:4555
cs_file_seek_t
Definition: cs_file.h:74
@ CS_FILE_SEEK_SET
Definition: cs_file.h:76
@ CS_FILE_SEEK_END
Definition: cs_file.h:78
@ CS_FILE_SEEK_CUR
Definition: cs_file.h:77
cs_file_t * cs_file_open_serial(const char *name, cs_file_mode_t mode)
Create a file descriptor and open the associated file, using the serial IO on the root rank.
Definition: cs_file.cpp:2759
size_t cs_file_write_block(cs_file_t *f, const void *buf, size_t size, size_t stride, cs_gnum_t global_num_start, cs_gnum_t global_num_end)
Write data to a file, each associated process providing a contiguous part of this data.
Definition: cs_file.cpp:3349
const char * cs_file_access_name[]
Definition: cs_file.cpp:338
cs_file_mpi_positioning_t cs_file_get_mpi_io_positioning(void)
Get the positioning method for MPI-IO.
Definition: cs_file.cpp:4215
void cs_file_set_allow_read_global_eof(cs_file_t *f, bool allow_eof)
Definition: cs_file.cpp:2840
cs_file_mpi_positioning_t
Definition: cs_file.h:98
@ CS_FILE_MPI_INDIVIDUAL_POINTERS
Definition: cs_file.h:101
@ CS_FILE_MPI_EXPLICIT_OFFSETS
Definition: cs_file.h:100
void * cs_file_serializer_advance(cs_file_serializer_t *s, cs_gnum_t cur_range[2])
Advance a cs_file_serializer_t structure.
Definition: cs_file.cpp:4423
void cs_file_set_swap_endian(cs_file_t *f, int swap)
Set a file's byte-swapping behavior.
Definition: cs_file.cpp:2951