get_entry (3) - Linux Manuals

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

The entry will be stored in the gd_entry_t structure indicated by the entry argument, which must be allocated by the caller. Members available in this structure depend on the field type of the field queried. See below for a complete description of this data type.

Strings members in entry filled by this function (variously, depending on field type: field, the elements of the in_fields[] array, table; see below) will by dynamically allocated by get_entry() and should not point to allocated memory locations before calling this function. Only strings provided by the gd_entry_t for the particular field type described will be allocated. These strings should be deallocated with free(3) by the caller once they are no longer needed. The dirfile_free_entry_strings(3) function is provided as a convenience to do this.

The returned entry structure, including strings and their pointers may be freely modified by the caller.

RETURN VALUE

GD_E_BAD_CODE

The field specified by field_code was not found in the database.

GD_E_BAD_DIRFILE

The supplied dirfile was invalid.

GD_E_BAD_REPR

The representation suffix specified in field_code was not recognised.

GD_E_BAD_SCALAR

A scalar parameter used in the definition of the field was invalid. The dirfile error may be retrieved by calling get_error(3). A descriptive error string for the last error encountered can be obtained from a call to get_error_string(3).

THE ENTRY TYPE

typedef struct {
  ...

  const char  *field;          /* field code */
  gd_entype_t  field_type;     /* field type */
  int          fragment_index; /* format file fragment index */

  ...
} gd_entry_t;

GD_BIT_ENTRY,~GD_CONST_ENTRY,~GD_INDEX_ENTRY,~ GD_LINCOM_ENTRY,~GD_LINTERP_ENTRY,~GD_MULTIPLY_ENTRY,~ GD_PHASE_ENTRY,~GD_POLYNOM_ENTRY,~GD_RAW_ENTRY,~GD_SBIT_ENTRY,~ GD_STRING_ENTRY. GD_INDEX_ENTRY is a special field type used only for the implicit INDEX field. The meaning of the other symbols should be self-explanatory. The fragment_index member indicates the format file fragment in which this field is defined. This is an integer index to the Dirfile's list of parsed format file fragments. The name of the file corresponding to fragment_index may be obtained by calling get_fragmentname(3). A value of zero for this field indicates that the field is defined in the primary format file, the file called format in the root dirfile directory (see dirfile(5)). Remaining fields in the gd_entry_t structure depend on the value of field_type. Callers are advised to check field_type before attempting to access the remaining members. Members for different field types may be stored in the same physical location in core. Accordingly, attempting to access a member not declared for the appropriate field type will have unspecified results.

BIT and SBIT Members

typedef struct {
  ...

  const char *in_fields[1];     /* input field code */
  const char *scalar[2];        /* parameter field codes */
  gd_bit_t    bitnum;           /* first bit */
  gd_bit_t    numbits;          /* bit length */

  ...
} gd_entry_t;

CONST Members

typedef struct {
  ...

  gd_type_t   const_type;       /* data type in format file */

  ...
} gd_entry_t;

INDEX Members

LINCOM Members

typedef struct {
  ...

  int            n_fields;                  /* # of input fields */
  int            comp_scal;                 /* complex scalar flag */
  const char    *in_fields[GD_MAX_LINCOM];  /* input field code(s) */
  const char    *scalar[2 * GD_MAX_LINCOM]; /* param. field codes */
  double complex cm[GD_MAX_LINCOM];         /* scale factor(s) */
  double         m[GD_MAX_LINCOM];          /* scale factor(s) */
  double complex cb[GD_MAX_LINCOM];         /* offset terms(s) */
  double         b[GD_MAX_LINCOM];          /* offset terms(s) */

  ...
} gd_entry_t;

LINTERP Members

typedef struct {
  ...

  const char *table             /* linterp table filename */
  const char *in_fields[1];     /* input field code */

  ...
} gd_entry_t;

MULTIPLY Members

typedef struct {
  ...

  const char *in_fields[2];     /* input field codes */

  ...
} gd_entry_t;

PHASE Members

typedef struct {
  ...

  const char *in_fields[1];     /* input field code */
  const char *scalar[1];        /* parameter field codes */
  gd_shift_t  shift;            /* phase shift */

  ...
} gd_entry_t;

POLYNOM Members

typedef struct {
  ...

  int            poly_ord;                  /* polynomial order */
  int            comp_scal;                 /* complex scalar flag */
  const char    *in_fields[1];              /* input field code(s) */
  const char    *scalar[GD_MAX_POLY_ORD + 1];
                                            /* co-eff. field codes */
  double complex ca[GD_MAX_POLY_ORD + 1];   /* co-efficients(s) */
  double         a[GD_MAX_POLY_ORD + 1];    /* co-efficients(s) */

  ...
} gd_entry_t;

RAW Members

typedef struct {
  ...

  const char   *scalar[1];    /* parameter field codes */
  gd_spf_t      spf;          /* samples per frame on disk */
  gd_type_t     data_type;    /* data type on disk */

  ...
} gd_entry_t;

STRING Members

NOTES

  double        cm[GD_MAX_LINCOM][2];
  double        cb[GD_MAX_LINCOM][2];
  double        ca[GD_MAX_POLY_ORD + 1][2];