Provided by: libgetdata-dev_0.7.3-6_i386 bug

NAME

       gd_putdata -- write data to a dirfile database

SYNOPSIS

       #include <getdata.h>

       size_t gd_putdata(DIRFILE *dirfile, const char *field_code, off_t
              first_frame, off_t first_sample, size_t num_frames, size_t
              num_samples, gd_type_t data_type, const void *data_in);

DESCRIPTION

       The   gd_putdata()  function  writes  data  to  a  dirfile(5)  database
       specified by dirfile for the field field_code, which may not contain  a
       representation  suffix.   It  writes num_frames frames plus num_samples
       samples  to  this  field,  starting  first_sample  samples  past  frame
       first_frame.   The  data is read from the user-supplied buffer data_in,
       which is has a data type specified by data_type.  This interface cannot
       write to field representations.

       The  dirfile  argument  must point to a valid DIRFILE object previously
       created by a call to gd_open(3).

       The first sample written will be
              first_frame * samples_per_frame + first_sample
       as measured from the start of the dirfile, where  samples_per_frame  is
       the  number  of samples per frame as returned by gd_spf(3).  The number
       of samples which gd_putdata() attempts to write is, similarly,
              num_frames * samples_per_frame + num_samples.
       Although  calling  gd_putdata()  using  both  samples  and  frames   is
       possible,  the function is typically called with either num_samples and
       first_sample, or num_frames and first_frames, equal to zero.

       The data_type argument should be one of the  following  symbols,  which
       indicates the type of the input data:

              GD_UINT8   unsigned 8-bit integer

              GD_INT8    signed (two's complement) 8-bit integer

              GD_UINT16  unsigned 16-bit integer

              GD_INT16   signed (two's complement) 16-bit integer

              GD_UINT32  unsigned 32-bit integer

              GD_INT32   signed (two's complement) 32-bit integer

              GD_UINT64  unsigned 64-bit integer

              GD_INT64   signed (two's complement) 64-bit integer

              GD_FLOAT32 or GD_FLOAT
                         IEEE-754  standard  32-bit  single precision floating
                         point number

              GD_FLOAT64 or GD_DOUBLE
                         IEEE-754 standard 64-bit  double  precision  floating
                         point number

       The type of the input data need not be the same as the type of the data
       stored in the database.  Type conversion will be performed as necessary
       to  write  the  appropriate type.  The argument data_in must point to a
       valid memory location of containing all the data to be written.

RETURN VALUE

       In all cases, gd_putdata() returns the number of  samples  (not  bytes)
       successfully written to the database, which may be zero if an error has
       occurred.

       If an error has occurred, the dirfile error will be set to  a  non-zero
       value.  Possible error values are:

       GD_E_ACCMODE
               The specified dirfile was opened read-only.

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_CODE
               The field specified by field_code, or one of the fields it uses
               for input, was not found in the database.

       GD_E_BAD_DIRFILE
               An invalid dirfile was supplied.

       GD_E_BAD_FIELD_TYPE
               Either the field specified by field_code, or one of the  fields
               it  uses  for  input, was of MULTIPLY or DIVIDE type, or LINCOM
               type  with  more  than  one  input  fields.   In   this   case,
               gd_putdata()  has  no  knowledge  on how to partition the input
               data.  Alternately, the caller may have attempted to  write  to
               the implicit INDEX field, which is not possible.

       GD_E_BAD_REPR
               The  representation  suffix  specified  in  field_code  was not
               recognised, or  an  attempt  was  made  to  write  to  a  field
               representation, instead of the underlying field.

       GD_E_BAD_TYPE
               An invalid data_type was specified.

       GD_E_DIMENSION
               A scalar field was found where a vector field was expected.

       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.

       GD_E_OPEN_LINFILE
               An  error  occurred  while  trying to read a LINTERP table from
               disk.

       GD_E_PROTECTED
               The data of the RAW field backing field_code was protected from
               change by a /PROTECT directive.

       GD_E_RANGE
               An attempt was made to write data before the beginning-of-frame
               marker for field_code, or the raw field it depends on.

       GD_E_RAW_IO
               An error occurred while trying to open, read from, or write  to
               a file on disk containing a raw field.

       GD_E_RECURSE_LEVEL
               Too  many  levels of recursion were encountered while trying to
               resolve  field_code.   This  usually   indicates   a   circular
               dependency in field specification in the dirfile.

       GD_E_UNSUPPORTED
               Reading from dirfiles with the encoding scheme of the specified
               dirfile  is  not  supported  by  the  library.   See   dirfile-
               encoding(5) for details on dirfile encoding schemes.

       The   dirfile  error  may  be  retrieved  by  calling  gd_error(3).   A
       descriptive error string for the last error encountered can be obtained
       from a call to gd_error_string(3).

SEE ALSO

       dirfile(5),      dirfile-encoding(5),      gd_open(3),     gd_error(3),
       gd_error_string(3),          gd_getdata(3),           gd_put_carray(3),
       gd_put_constant(3), gd_spf(3)