---
name: "gd_get_sarray"
section: "3"
platform: "linux"
package: "libgetdata-doc"
version: "0.11.0-15"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/gd_get_sarray_slice"
---

# gd\_get\_sarray(3)

retrieve STRING or SARRAY data from a dirfile database

Part of [gd\_get\_sarray\_slice(3)](/gd_get_sarray_slice/3.md).

## NAME

gd\_get\_sarray, gd\_get\_sarray\_slice — retrieve STRING or SARRAY data from a dirfile database

## SYNOPSIS

**#include \<getdata.h\>**

**int gd\_get\_sarray\_slice(DIRFILE \****dirfile***, const char \****field\_code***,** **unsigned int** *start***, size\_t** *len***, const char \*\****data\_out***);**

**int gd\_get\_sarray(DIRFILE \****dirfile***, const char \****field\_code***,** **const char \*\****data\_out***);**

## DESCRIPTION

The **gd\_get\_sarray\_slice**() function queries a [dirfile(5)](/dirfile/5.md) database specified by *dirfile* for the **STRING** or **SARRAY** scalar *field\_code*. Pointers to read-only string elements of the specified field are stored in the user-supplied  *data\_out* buffer, which must be large enough to hold *len* pointers.  The first element of the field stored is given by *start*, and the number of elements stored is given by *len*.

The **gd\_get\_sarray**() function behaves similarly, except it returns the entire field, as if **gd\_get\_sarray\_slice**() were called with *start* equal to zero and *len* equal to the value returned by [**gd\_array\_len**(3)](/gd_array_len/3.md).

The  *dirfile* argument must point to a valid DIRFILE object previously created by a call to [**gd\_open**(3)](/gd_open/3.md). The number of elements returned by **gd\_get\_sarray**() may be obtained by calling [**gd\_array\_len**(3)](/gd_array_len/3.md). Unlike [**gd\_getdata**(3)](/gd_getdata/3.md), calling **gd\_get\_sarray\_slice**() never results in a short read; attempting to read past the end of the field will result in an error, and no data will be returned.

If *field\_code* refers to a **STRING** field, it is treated as if it were a **SARRAY** field with only one element.  See the [**gd\_get\_string**(3)](/gd_get_string/3.md) manual page for an example of how to replace [**gd\_get\_string**(3)](/gd_get_string/3.md) calls with **gd\_get\_sarray**().

## RETURN VALUE

On success, **gd\_get\_sarray**() and **gd\_get\_sarray\_slice**(), return zero.  Storage for the strings returned by this function are managed by GetData and should not be deallocated by the caller.  On error, these functions return a negative-valued error code.  Possible error codes are:\
  .TP 8 **GD\_E\_ALLOC** The library was unable to allocate memory.\
  .TP 8 **GD\_E\_BAD\_CODE** The field specified by *field\_code* was not found in the database.\
  .TP 8 **GD\_E\_BAD\_DIRFILE** An invalid *dirfile* was supplied.\
  .TP 8 **GD\_E\_BAD\_FIELD\_TYPE** The supplied *field\_code* was not a **STRING** nor **SARRAY**.\
  .TP 8 **GD\_E\_BOUNDS** A request for data beyond the end of the field was made.\
  .TP 8 **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 maintainer.

The error code is also stored in the **DIRFILE** object and may be retrieved after this function returns by calling [**gd\_error**(3)](/gd_error/3.md). A descriptive error string for the error may be obtained by calling [**gd\_error\_string**(3)](/gd_error_string/3.md).

## HISTORY

The **gd\_get\_sarray**() and **gd\_get\_sarray\_slice**() functions appeared in GetData-0.10.0.

## SEE ALSO

[**gd\_array\_len**(3)](/gd_array_len/3.md), [**gd\_get\_string**(3)](/gd_get_string/3.md), [**gd\_error**(3)](/gd_error/3.md), [**gd\_error\_string**(3)](/gd_error_string/3.md), [**gd\_open**(3)](/gd_open/3.md), [**gd\_put\_sarray\_slice**(3)](/gd_put_sarray_slice/3.md), [**gd\_sarrays**(3)](/gd_sarrays/3.md), [dirfile(5)](/dirfile/5.md)