.\" header.tmac.  GetData manual macros.
.\"
.\" Copyright (C) 2016 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.

.\" Format a function name with optional trailer: func_name()trailer
.de FN \" func_name [trailer]
.nh
.BR \\$1 ()\\$2
.hy
..

.\" Format a reference to section 3 of the manual: name(3)trailer
.de F3 \" func_name [trailer]
.nh
.BR \\$1 (3)\\$2
.hy
..

.\" Format the header of a list of definitons
.de DD \" name alt...
.ie "\\$2"" \{ \
.TP 8
.PD
.B \\$1 \}
.el \{ \
.PP
.B \\$1
.PD 0
.DD \\$2 \\$3 \}
..

.\" Start a code block: Note: groff defines an undocumented .SC for
.\" Bell Labs man legacy reasons.
.de SC
.fam C
.na
.nh
..

.\" End a code block
.de EC
.hy
.ad
.fam
..

.\" Format a structure pointer member: struct->member\fRtrailer
.de SPM \" struct member trailer
.nh
.ie "\\$3"" .IB \\$1 ->\: \\$2
.el .IB \\$1 ->\: \\$2\fR\\$3
.hy
..

.\" Format a function argument
.de ARG \" name trailer
.nh
.ie "\\$2"" .I \\$1
.el .IR \\$1 \\$2
.hy
..

.\" Hyphenation exceptions
.hw sarray carray lincom linterp
.\" gd_sarrays.3.  The gd_sarrays man page.
.\"
.\" Copyright (C) 2010, 2011, 2016 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_sarrays 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_sarrays, gd_msarrays \(em retrieve a list of SARRAY values from a Dirfile

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "const char ***gd_sarrays(DIRFILE *" dirfile );
.HP
.BI "const char ***gd_msarrays(DIRFILE *" dirfile ", const char"
.BI * parent );
.EC

.SH DESCRIPTION
The
.FN gd_sarrays
function queries a dirfile(5) database specified by
.ARG dirfile
and generates a read-only list of values of the all top-level
.B SARRAY
fields defined in the database, after type conversion to the data type
specified by
.ARG return_type .
For a list of valid symbols to use for
.ARG return_type ,
see the
.F3 gd_get_sarray
manual page.  

The
.FN gd_msarrays
function behaves similarly, but creates a list of values of
.B SARRAY
subfields under the parent field
.ARG parent .

The 
.ARG dirfile
argument must point to a valid DIRFILE object previously created by a call to
.F3 gd_open .

The array returned will be de-allocated by a call to
.F3 gd_close
and should not be de-allocated by the caller.  The list returned should not be
assumed to be in any particular order, except that it is guaranteed to be in the
same order as the list of
.B SARRAY
fields returned by
.F3 gd_field_list_by_type
or
.F3 gd_mfield_list_by_type .
The number of values in the array can be obtained from a call to
.F3 gd_nfields_by_type
or
.F3 gd_nmfields_by_type .

The caller may not modify any values in the array, nor the array itself.  Doing
so may cause database corruption.  The pointer returned is guaranteed to be
valid only until the function is called again with the same arguments, or until
the dirfile's metadata is modified (by adding, modifying or deleting an entry),
or until the array is de-allocated by a call to
.F3 gd_close
or
.F3 gd_discard .

A corresponding list of names for these fields may be obtained by calling
.F3 gd_field_list_by_type
or
.F3 gd_mfield_list_by_type .

.SH RETURN VALUE
Upon successful completion,
.FN gd_sarrays
and
.F3 gd_msarrays
return a pointer to an array of arrays of strings.  For convenience, both
levels of the array are terminated by NULL pointers.

If no SARRAYs are defined in the database, a pointer to a single-element array
containing only the terminating NULL is returned.

On error,
.FN gd_sarrays
returns NULL and stores a negative-valued error code in the
.B DIRFILE
object which may be retrieved by a subsequent call to
.F3 gd_error .
Possible error codes are:
.DD GD_E_ALLOC
The library was unable to allocate memory.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_INTERNAL_ERROR
An internal error occurred in the library while trying to perform the task.
This indicates a bug in the library.  Please report the incident to the
GetData developers.
.PP
A descriptive error string for the error may be obtained by calling
.F3 gd_error_string .

.SH HISTORY
The
.FN gd_sarrays
function appeared in GetData-0.10.0.

.SH SEE ALSO
.F3 gd_entry_list ,
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_get_sarray ,
.F3 gd_nentries ,
.F3 gd_open ,
dirfile(5)