OpenMPI  0.1.1
f77_strings.h
1 /*
2  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
3  * University Research and Technology
4  * Corporation. All rights reserved.
5  * Copyright (c) 2004-2005 The University of Tennessee and The University
6  * of Tennessee Research Foundation. All rights
7  * reserved.
8  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9  * University of Stuttgart. All rights reserved.
10  * Copyright (c) 2004-2005 The Regents of the University of California.
11  * All rights reserved.
12  * Copyright (c) 2010 Cisco Systems, Inc. All rights reserved.
13  * $COPYRIGHT$
14  *
15  * Additional copyrights may follow
16  *
17  * $HEADER$
18  */
19 
20 #ifndef OMPI_F77_STRINGS_H
21 #define OMPI_F77_STRINGS_H
22 
23 #include "ompi_config.h"
24 
25 BEGIN_C_DECLS
26  /**
27  * Convert a fortran string to a C string.
28  *
29  * @param fstr Fortran string
30  * @param len Fortran string length
31  * @param cstr Pointer to C string that will be created and returned
32  *
33  * @retval OMPI_SUCCESS upon success
34  * @retval OMPI_ERROR upon error
35  *
36  * This function is intended to be used in the MPI F77 bindings to
37  * convert fortran strings to C strings before invoking a back-end
38  * MPI C binding function. It will create a new C string and
39  * assign it to the cstr to return. The caller is responsible for
40  * eventually freeing the C string.
41  */
42  OMPI_DECLSPEC int ompi_fortran_string_f2c(char *fstr, int len, char **cstr);
43 
44  /**
45  * Convert a C string to a fortran string.
46  *
47  * @param cstr C string
48  * @param fstr Fortran string (must already exist and be allocated)
49  * @param len Fortran string length
50  *
51  * @retval OMPI_SUCCESS upon success
52  * @retval OMPI_ERROR upon error
53  *
54  * This function is intended to be used in the MPI F77 bindings to
55  * convert C strings to fortran strings. It is assumed that the
56  * fortran string is already allocated and has a length of len.
57  */
58  OMPI_DECLSPEC int ompi_fortran_string_c2f(char *cstr, char *fstr, int len);
59 
60  /**
61  * Convert an array of Fortran strings to an argv-style array of C
62  * strings.
63  *
64  * @param farray Array of fortran strings
65  * @param string_len Length of each fortran string in the array
66  * @param advance Number of bytes to advance to get to the next string
67  * @param cargv Returned argv-style array of C strings
68  *
69  * @retval OMPI_SUCCESS upon success
70  * @retval OMPI_ERROR upon error
71  *
72  * This function is intented to be used in the MPI F77 bindings to
73  * convert arrays of fortran strings to argv-style arrays of C
74  * strings. The argv array will be allocated and returned; it is
75  * the caller's responsibility to invoke opal_argv_free() to free
76  * it later (or equivalent).
77  *
78  * For 1D Fortran string arrays, advance will == string_len.
79  *
80  * However, when this function is used (indirectly) for
81  * MPI_COMM_SPAWN_MULTIPLE, a 2D array of Fortran strings is
82  * converted to individual C-style argv vectors. In this case,
83  * Fortran will intertwine the strings of the different argv
84  * vectors in memory; the displacement between the beginning of 2
85  * strings in a single argv vector is (string_len *
86  * number_of_argv_arrays). Hence, the advance parameter is used
87  * to specify this displacement.
88  */
89  OMPI_DECLSPEC int ompi_fortran_argv_f2c(char *farray, int string_len,
90  int advancex, char ***cargv);
91 
92  /**
93  * Convert an array of argvs to a C style array of argvs
94  * @param count Dimension of the array of argvs
95  * @param array Array of fortran argv
96  * @param len Length of Fortran array
97  * @param argv Returned C arrray of argvs
98  *
99  * This function is intented to be used in the MPI F77 bindings to
100  * convert arrays of fortran strings to argv-style arrays of C
101  * strings. The argv array will be allocated and returned; it is
102  * the caller's responsibility to invoke opal_argv_free() to free
103  * each content of argv array and call free to deallocate the argv
104  * array itself
105  */
106  OMPI_DECLSPEC int ompi_fortran_multiple_argvs_f2c(int count, char *array, int len,
107  char ****argv);
108 
109 END_C_DECLS
110 
111 
112 #endif /* OMPI_F77_STRINGS_H */