---
name: "gd_put_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_put_sarray_slice"
---

# gd\_put\_sarray(3)

write STRING or SARRAY data to a Dirfile database

Part of [gd\_put\_sarray\_slice(3)](/gd_put_sarray_slice/3.md).

## NAME

gd\_put\_sarray, gd\_put\_sarray\_slice — write STRING or SARRAY data to a Dirfile database

## SYNOPSIS

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

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

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

## DESCRIPTION

The **gd\_put\_sarray\_slice**() function writes string data to a [dirfile(5)](/dirfile/5.md) database specified by *dirfile* into the **STRING** or **SARRAY** scalar array *field\_code*. The location of the first element of the field into which data is stored is given by *start*, and the number of elements stored is given by *len*.

If *field\_code* specifies a **STRING** field, it is treated as if it were a **SARRAY** field of length one.

The **gd\_put\_sarray**() function behaves similarly, except the whole scalar array is written, as if **gd\_put\_sarray\_slice**() were called with *start* equal zero and *len* equal to the value returned by [**gd\_array\_len**(3)](/gd_array_len/3.md).

The argument *data\_in* must point to an array of pointers to character strings, which are the values to store.  The number of elements which will be stored by **gd\_put\_sarray**() may be obtained by calling [**gd\_array\_len**(3)](/gd_array_len/3.md). Unlike [**gd\_putdata**(3)](/gd_putdata/3.md), writing data past the end of the field is not permitted.  To add data to a **SARRAY**, first increase its length by calling **gd\_alter\_sarray**(3), or another equivalent function.

The [**gd\_put\_string**(3)](/gd_put_string/3.md) function provides another way of writing data to a **STRING** field.

## RETURN VALUE

On success, **gd\_put\_sarray**() and **gd\_put\_sarray\_slice**() return zero.  On error, they return a negative-valued error code.  Possible error codes are:\
  .TP 8 **GD\_E\_ACCMODE** The specified *dirfile* was opened read-only.\
  .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 a **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.\
  .TP 8 **GD\_E\_PROTECTED** The fragment containing the constant was protected from change.

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\_put\_sarray**() and **gd\_put\_sarray\_slice**() functions appeared in GetData-0.10.0.

## SEE ALSO

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