Linux Certif

Toute la documentation sur la certification Linux LPI

get_entry

NAME

get_entry --- retrieve a dirfile field's metadata

SYNOPSIS

#include <getdata.h>

int get_entry(DIRFILE *dirfile, const char *field_code, gd_entry_t *entry);

DESCRIPTION

The get_entry() function queries a dirfile(5) database specified by dirfile and returns the metadata associated with the field specified by field_code.

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.

RETURN VALUE

Upon successful completion, get_entry() returns zero, and writes the field metadata in the supplied gd_entry_t buffer. On error, get_entry() returns -1 and sets the dirfile error to a non-zero error value. Possible error values are:

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.

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

Members available in the gd_entry_t structure depend on the field type described. All gd_entry_t objects are guaranteed to have at least:

 typedef struct {
   ...
 
   const char  *field;          /* field code */
   gd_entype_t  field_type;     /* field type */
   int          fragment_index; /* format file fragment index */
 
   ...
 } gd_entry_t;
 

The field member is the field code of the entry (i.e. its string name). If the call to get_entry(3) is successful, this will be identical to the supplied field_code argument.

The field_type member indicates the field type of the entry. This is an integer type equal to one of the following symbols:

GD_BIT_ENTRY,~GD_CONST_ENTRY,~GD_INDEX_ENTRY,~ GD_LINCOM_ENTRY,~GD_LINTERP_ENTRY,~GD_MULTIPLY_ENTRY,~ GD_PHASE_ENTRY,~GD_RAW_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 Members

A gd_entry_t describing a BIT entry, will also provide:

 typedef struct {
   ...
 
   const char *in_fields[1];     /* input field code */
   int         bitnum;           /* first bit */
   int         numbits;          /* bit length */
 
   ...
 } gd_entry_t;
 

The in_fields member is an array of length 1 containing the input field code.

The bitnum member indicates the number of the first bit (counted from zero) extracted from the input.

The numbits member indicates the number of bits which are extracted from the input.

CONST Members

A gd_entry_t describing a CONST entry, will also provide:

 typedef struct {
   ...
 
   gd_type_t   const_type;       /* data type in format file */
 
   ...
 } gd_entry_t;
 

The const_type member indicates the data type of the constant value stored in the format file metadata. See getdata(3) for a list of valid values that a variable of type gd_type_t may take.

INDEX Members

A gd_entry_t describing an INDEX entry, which is used only for the implicit INDEX field, provides no additional data.

LINCOM Members

A gd_entry_t describing a LINCOM entry, will also provide:

 typedef struct {
   ...
 
   int         n_fields;                 /* number of input fields */
   const char *in_fields[GD_MAX_LINCOM]; /* input field code(s) */
   double      m[GD_MAX_LINCOM];         /* scale factor(s) */
   double      b[GD_MAX_LINCOM];         /* offset terms(s) */
 
   ...
 } gd_entry_t;
 

The count member indicates the number of input fields. It will be between one and GD_MAX_LINCOM, which is defined in getdata.h to the maximum number of input fields permitted by a LINCOM.

The in_fields member is an array of length GD_MAX_LINCOM containing the input field code(s). Only the first count records from this array are initialised. The remaining records will contain invalid data.

The m and b members are arrays of the scale factor(s) and offset term(s) for the LINCOM. Attempting to access more than the first count records from these array may result in undefined behaviour.

LINTERP Members

A gd_entry_t describing a LINTERP entry, will also provide:

 typedef struct {
   ...
 
   const char *table             /* linterp table filename */
   const char *in_fields[1];     /* input field code */
 
   ...
 } gd_entry_t;
 

The table member is the pathname to the look up table on disk.

The in_fields member is an array of length 1 containing the input field code.

MULTIPLY Members

A gd_entry_t describing a MULTIPLY entry, will also provide:

 typedef struct {
   ...
 
   const char *in_fields[2];     /* input field codes */
 
   ...
 } gd_entry_t;
 

The in_fields member is an array of length 2 containing the input field codes.

PHASE Members

A gd_entry_t describing a PHASE entry, will also provide:

 typedef struct {
   ...
 
   const char *in_fields[1];     /* input field code */
   int         shift;            /* phase shift */
 
   ...
 } gd_entry_t;
 

The in_fields member is an array of length 1 containing the input field code.

The shift member indicates the shift in samples. A positive value indicates a shift forward in time (towards larger frame numbers).

RAW Members

A gd_entry_t describing a RAW entry, will also provide:

 typedef struct {
   ...
 
   unsigned int  spf;          /* samples per frame on disk */
   gd_type_t     data_type;    /* data type on disk */
 
   ...
 } gd_entry_t;
 

The samples_per_frame member contains the samples per frame of the binary data on disk.

The data_type member indicates the data type of the binary data on disk. See getdata(3) for a list of valid values that a variable of type gd_type_t may take.

STRING Members

A gd_entry_t describing a STRING entry provides no additional data.

SEE ALSO

dirfile(5), dirfile_free_entry_strings(3), dirfile_open(3), getdata(3), get_error(3), get_error_string(3), get_field_list(3), get_fragmentname(3), get_raw_filename(3)