.\" gd_linterp_tablename.3.  The gd_linterp_tablename man page.
.\"
.\" Copyright (C) 2012, 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_linterp_tablename 3 "10 December 2013" "Version 0.9.0" "GETDATA"
.SH NAME
gd_linterp_tablename \(em retrieve the pathname of a look-up table in a dirfile
.SH SYNOPSIS
.B #include <getdata.h>
.HP
.nh
.ad l
.BI "char *gd_linterp_tablename(DIRFILE *" dirfile ", const char"
.BI * field_code );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_linterp_tablename ()
function retrieves the pathname of the look-up table (LUT) used by the
.B LINTERP
field specified by
.I field_code
in the dirfile specified by
.IR dirfile .
If
.I field_code
contains a valid representation suffix, it will be ignored.

Note: this function returns a fully canonicalised, absolute path.  The value of
the
.I table
member in a
.B gd_entry_t
object (see
.BR gd_entry (3))
is the path which appears in the format specification on disk, which may be a
path relative to the fragment directory.

.SH RETURN VALUE
On success,
.BR gd_linterp_tablename ()
returns the full pathname of the LUT associated with the specified field in a
buffer allocated by
.BR malloc (3).  
Once no longer needed, the returned pointer should be passed to
.BR free (3)
to deallocate the associated memory.  On error, NULL is returned and the dirfile
error is set to a non-zero error value.  Possible error values are:
.TP 8
.B GD_E_ALLOC
The library was unable to allocate memory.
.TP
.B GD_E_BAD_CODE
The field specified by
.I field_code
was not found.
.TP
.B GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.TP
.B GD_E_BAD_FIELD_TYPE
The field specified by
.I field_code
was not a
.B LINTERP
field.
.PP
The dirfile error may be retrieved by calling
.BR gd_error (3).
A descriptive error string for the last error encountered can be obtained from
a call to
.BR gd_error_string (3).
.SH SEE ALSO
.BR gd_entry (3),
.BR gd_error (3),
.BR gd_error_string (3),
.BR dirfile (5),
.BR dirfile-format (5),
.BR free (3),
.BR malloc (3)