.\" gd_free_entry_strings.3.  The gd_free_entry_strings man page.
.\"
.\" Copyright (C) 2008, 2010, 2013 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_free_entry_strings 3 "7 December 2013" "Version 0.9.0" "GETDATA"
.SH NAME
gd_free_entry_strings \(em free strings in a GetData gd_entry_t object
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "gd_entry_t *gd_free_entry_strings(gd_entry_t *" entry );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_free_entry_strings ()
function frees the character strings found in the gd_entry_t object
.I entry
which were previously allocated by a call to
.BR gd_entry (3).
After freeing a string, the associated pointer is set to NULL.  If
.I entry
is NULL, this function does nothing.

If non-NULL,
.I entry
must point to a valid and properly initialised gd_entry_t object, such as that
returned by
.BR 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
.I entry
have not been allocated with
.BR malloc (3),
unless these pointer members are equal to NULL.

See 
.BR gd_entry (3)
for a description of the gd_entry_t data type.
.SH RETURN VALUE
The function
.BR gd_free_entry_strings ()
always returns its input,
.IR entry .
.SH NOTES
This function is provided as a convenience only.  Callers may free strings
allocated by
.BR gd_entry (3)
themselves by simply calling
.BR free (3)
on the appropriate members for the given entry type, if they prefer to do so.
.SH SEE ALSO
.BR gd_entry (3),
.BR free (3)