Previous: sfor2c Up: Fortran String Conversion Routines Next: sfor2len

sfor2c_array

sfor2c_array(c_string, max_length, nelements, for_string, argptr, nargs,
             argno, strno);

This routine converts a Fortran string array to a standard C null-terminated array of strings. The returned C string array is a two-dimensional array of characters, not an array of pointers to strings. The Fortran string should be declared as a single-dimensional array of CHARACTER*n in the calling routine.

This routine is somewhat unusual in that it actually allocates the memory for the C string for you. You pass in the address of a character pointer, not the address of a buffer for the characters. sfor2c_array calls malloc() to allocate the required memory, and returns the address of that memory in the pointer. It is your responsibility to call free() to free up that memory when you are done with it.

Arguments:

• C_STRING: pointer to string array, output

  C_STRING is the address of a pointer that will be filled in to point at the string array. The returned array will be a two-dimensional array of characters, not an array of pointers to strings. Each string will have its own null terminator.

  This routine actually allocates the memory for the C string for you. C_STRING is the address of a character pointer, not the address of a buffer for the characters. sfor2c_array calls malloc() to allocate the required memory, and returns the address of that memory in C_STRING. It is your responsibility to call free() to free up that memory when you are done with it.

  The inner dimension of the array is returned via the MAX_LENGTH parameter. Since you don't know this size at compile time, you can't access the strings like a normal two-dimensional array. It is easy enough to do your own addressing, however. For example:

  
  char *array;
  int maxlen=0;
  ...
  sfor2c\_array(&array, &maxlen, ...);
  ...
  process_string(array+(i*maxlen));       /* to get at the i'th string */
  

• MAX_LENGTH: integer, input/output

  On input, MAX_LENGTH is the alternate maximum length of each Fortran string. Normally the maximum length is obtained from the input Fortran string array itself (the ``n'' in a CHARACTER*n declaration). If MAX_LENGTH is passed in as 0, then this natural length is used. MAX_LENGTH is an alternate maximum string length in case one is provided as a parameter to the routine. The actual maximum Fortran length used is the minimum of the passed in MAX_LENGTH (if not 0) and the natural Fortran string length. MAX_LENGTH should almost always be passed in as 0, as it makes little sense to override the natural Fortran string length, especially on an array. However, it is possible, and might be useful in some unusual cases.

  On output, MAX_LENGTH returns the size of the inner dimension of the C string array that was allocated by sfor2c_array. To access the i'th string in the array, simply add i*maxlen to the returned array pointer.

• NELEMENTS: integer, input

  NELEMENTS is the number of strings in the array to convert.

• FOR_STRING, ARGPTR, NARGS, ARGNO, STRNO

  See the ``Common Features'' section above.