gd_free_entry_strings(3) [debian man page]
gd_free_entry_strings(3) GETDATA gd_free_entry_strings(3) NAME
gd_free_entry_strings -- free strings in a GetData gd_entry_t object SYNOPSIS
#include <getdata.h> gd_entry_t *gd_free_entry_strings(gd_entry_t *entry); DESCRIPTION
The gd_free_entry_strings() function frees the character strings found in the gd_entry_t object entry which were previously allocated by a call to gd_entry(3). If entry is NULL, this function does nothing. If non-NULL, entry must point to a valid and properly initialised gd_entry_t object, such as that returned by gd_entry(3). As well, the caller may construct a properly initialised gd_entry_t object by first setting all bits to zero, then setting the field_type parameter to the desired gd_entype_t symbol, and finally initialising only the members defined for that type. The results of calling this function are undefined if the character strings pointed to by the string members of entry have not been allocated with malloc(3), unless these pointer members are equal to NULL. See gd_entry(3) for a complete description of the gd_entry_t data type. RETURN VALUE
A call to gd_free_entry_strings() always returns its input, entry. NOTES
This function is provided as a convenience only. Callers may free strings allocated by gd_entry(3) themselves by simply calling free(3) on the appropriate members for the given entry type, if they prefer to do so. SEE ALSO
gd_entry(3), free(3) Version 0.7.0 16 June 2010 gd_free_entry_strings(3)
Check Out this Related Man Page
gd_alter_entry(3) GETDATA gd_alter_entry(3) NAME
gd_alter_entry -- modify the metadata of a dirfile field SYNOPSIS
#include <getdata.h> int gd_alter_entry(DIRFILE *dirfile, const char *field_code, const gd_entry_t *entry, int recode); DESCRIPTION
The gd_alter_entry() function modifies the field specified by field_code in the dirfile specified by dirfile to correspond to the new pa- rameters specified by entry. In addition to specifying a regular field, field_code may also refer to a metafield by specifying it using its full (slashed) field code. However, field_code should never contain a representation suffix. The form of entry is described in detail in the get_entry(3) man page. The entry->field and entry->fragment_index members are ignored by this function and need not be initialised. All other members appropriate to the field type of field_code should be initialised, except as noted below. To change the fragment index of a field, use gd_move(3). To change the name of a field, use gd_rename(3). If field_code specifies a RAW field and the recode argument is non-zero, the binary file associated with the field will be converted for changes in data type and samples-per-frame. If recode is zero, no binary file conversion will take place. If field_code specifies a LINTERP field and the recode argument is non-zero, the look-up table file will be moved if entry->table specifies a different path. If a file with the new pathname already exists, it will be overwritten. If the field specified by field_code is of type other than RAW or LINTERP, the recode argument is ignored. If field_code specified a LINCOM or POLYNOM field, the value of entry->comp_scal indicates whether the purely real scalar lists (entry->a, or entry->b and entry->m) or the complex valued lists (entry->ca, or entry->cb and entry->cm) will be used. The unused counterparts need not be initialised. The entry->field_type member must correspond to the field type of field_code. This interface cannot be used to change the type of a given field. To do so, delete the old field first with gd_delete(3), and then create a new field of the desired type with gd_add(3). Some field parameters have special values which indicate no change should be made to the parameter. Specifically, if any of the string pa- rameters, or the parameters (entry->a, entry->b, entry->m, entry->ca, entry->cb, or entry->cm) are NULL, the old values will be retained. Similarly, if entry->spf, entry->n_fields, or entry->numbits is zero, or if entry->bitnum is -1, or if entry->data_type, or entry->con- st_type are equal to GD_NULL, these parameters will not be modified. All entry->scalar elements relevant for the given field type must be initialised to one of the following values: o a pointer to a field code indicating a new scalar field to be used for the corresponding field parameter. If the parameter was previ- ously a literal number, it will be replaced by the specified field code. If the parameter was previously a field code, the new field code will replace the old one. If the field code specifies a CARRAY field, the corresponding entry->scalar_ind element should also be set. o a pointer the empty string (""). In this case, no change is made to the field code for the corresponding field parameter: if one al- ready existed, it is kept, otherwise the corresponding literal numerical parameter is used. If the value of the corresponding numeri- cal entry member is the special value listed above indicating no change, no change is made to the field parameter at all. o the NULL pointer. If the corresponding field parameter was previously a field code, the field code will be deleted and a literal num- ber used instead. In the special case when a scalar element is NULL and the corresponding numerical entry member contains a special value indicating no change listed above, GetData will de-reference the previous field code value and convert it into a literal number before removing the field code from the entry. RETURN VALUE
On success, gd_alter_entry() returns zero. On error, -1 is returned and the dirfile error is set to a non-zero error value. Possible er- ror 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 was not found. This error may also result from attempting to dereference a scalar field code which indicates a non-existent field. GD_E_BAD_DIRFILE The supplied dirfile was invalid. GD_E_BAD_ENTRY One or more of the parameters specified in entry was invalid. GD_E_BAD_FIELD_TYPE The entry->field_type parameter did not correspond to the type of the field specified by field_code, or an attempt was made to mod- ify the immutable INDEX field. This error may also result from attempting to dereference a scalar field code which does not indi- cate a CONST or CARRAY field. GD_E_BAD_TYPE The entry->data_type parameter provided with a RAW entry, or the entry->const_type parameter provided with a CONST or CARRAY entry, was invalid. GD_E_PROTECTED The metadata of the fragment was protected from change. Or, a request to translate the binary file associated with a RAW field was attempted, but the data of the fragment was protected. GD_E_RAW_IO An I/O error occurred while translating the binary file associated with a modified RAW field, or an I/O error occurred while at- tempting to rename a LINTERP table file. GD_E_UNKNOWN_ENCODING The encoding scheme of the indicated format specification fragment is not known to the library. As a result, the library was un- able to translate the binary file be associated with a modified RAW field. GD_E_UNSUPPORTED The encoding scheme of the indicated format specification fragment does not support translating the binary file associated with a modified RAW field. 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
gd_alter_bit(3), gd_alter_carray(3), gd_alter_const(3), gd_alter_divide(3), gd_alter_lincom(3), gd_alter_linterp(3), gd_alter_multiply(3), gd_alter_phase(3), gd_alter_polynom(3), gd_alter_raw(3), gd_alter_recip(3), gd_alter_spec(3), gd_delete(3), gd_error(3), gd_er- ror_string(3), gd_malter_spec(3), gd_metaflush(3), gd_move(3), gd_open(3), gd_rename(3), dirfile-format(5) Version 0.7.0 3 November 2010 gd_alter_entry(3)