[Getdata-commits] SF.net SVN: getdata:[933] branches/getdata-0.8
Scientific Database Format
Brought to you by:
ketiltrout
Menu
▾
▴
[Getdata-commits] SF.net SVN: getdata:[933] branches/getdata-0.8
|
From: <ket...@us...> - 2014-12-06 07:48:57
|
Revision: 933
http://sourceforge.net/p/getdata/code/933
Author: ketiltrout
Date: 2014-12-06 07:48:51 +0000 (Sat, 06 Dec 2014)
Log Message:
-----------
Doc updates from trunk
Modified Paths:
--------------
branches/getdata-0.8/man/gd_add_bit.3
branches/getdata-0.8/man/gd_alter_bit.3
branches/getdata-0.8/man/gd_alter_encoding.3.in
branches/getdata-0.8/man/gd_alter_entry.3
branches/getdata-0.8/man/gd_linterp_tablename.3
branches/getdata-0.8/man/gd_madd_bit.3
branches/getdata-0.8/man/gd_naliases.3
branches/getdata-0.8/man/gd_raw_filename.3
Property Changed:
----------------
branches/getdata-0.8/
Index: branches/getdata-0.8
===================================================================
--- branches/getdata-0.8 2014-12-05 21:16:00 UTC (rev 932)
+++ branches/getdata-0.8 2014-12-06 07:48:51 UTC (rev 933)
Property changes on: branches/getdata-0.8
___________________________________________________________________
Modified: svn:ignore
## -28,3 +28,4 ##
README.txt
config.lt
compile
+test-driver
Modified: branches/getdata-0.8/man/gd_add_bit.3
===================================================================
--- branches/getdata-0.8/man/gd_add_bit.3 2014-12-05 21:16:00 UTC (rev 932)
+++ branches/getdata-0.8/man/gd_add_bit.3 2014-12-06 07:48:51 UTC (rev 933)
@@ -1,6 +1,6 @@
.\" gd_add_bit.3. The gd_add_bit man page.
.\"
-.\" Copyright (C) 2008, 2009, 2010, 2012 D. V. Wiebe
+.\" Copyright (C) 2008, 2009, 2010, 2012, 2013 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
@@ -13,7 +13,7 @@
.\" Texts. A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
-.TH gd_add_bit 3 "26 July 2012" "Version 0.8.1" "GETDATA"
+.TH gd_add_bit 3 "1 October 2013" "Version 0.8.6" "GETDATA"
.SH NAME
gd_add_bit, gd_add_carray gd_add_clincom, gd_add_const, gd_add_cpolynom,
gd_add_crecip, gd_add_divide, gd_add_lincom, gd_add_linterp, gd_add_multiply,
@@ -328,10 +328,10 @@
.HP
.BI "int gd_add_cpolynom(DIRFILE *" dirfile ", const char *" field_name ,
.BI "int " poly_ord ", const char *" in_fields ", const double *" ca ,
-.BI int " fragment_index );
+.BI "int " fragment_index );
.HP
.BI "int gd_add_crecip(DIRFILE *" dirfile ", const char *" field_name ,
-.BI "const char *" in_field ", double " cdividend [2],
+.BI "const char *" in_field ", const double " cdividend [2],
.BI "int " fragment_index );
.hy
.ad n
@@ -341,7 +341,7 @@
or
.IR ca
should have twice as many (purely real) elements, consisting of alternating
-real and imaginary parts for the complex data. For example,
+real and imaginary parts for the complex data. That is, for example,
.IR ca [0]
should be the real part of the first co-efficient,
.IR ca [1]
@@ -352,7 +352,24 @@
the imaginary part of the second co-efficient, and so on. Similarly, the
.I cdividend
parameter becomes a double precision array of length two.
+.PP
+For
+.BR gd_add_clincom ()
+and
+.BR gd_add_cpolynom (),
+these are simply different (but equivalent) declarations of the C99 function
+entry point. For
+.BR gd_add_crecip (),
+however, a different entry point is needed (since the
+.I cdividend
+parameter is passed by reference instead of by value). In the interests of
+portability, the C89 version of
+.BR gd_add_crecip ()
+is always available, and may be accessed as
+.BR gd_add_crecip89 (),
+with the C89 prototype, in both the C99 and C89 APIs.
+
.SH SEE ALSO
.BR gd_add (3),
.BR gd_add_spec (3),
Modified: branches/getdata-0.8/man/gd_alter_bit.3
===================================================================
--- branches/getdata-0.8/man/gd_alter_bit.3 2014-12-05 21:16:00 UTC (rev 932)
+++ branches/getdata-0.8/man/gd_alter_bit.3 2014-12-06 07:48:51 UTC (rev 933)
@@ -1,6 +1,6 @@
.\" gd_alter_bit.3. The gd_alter_bit man page.
.\"
-.\" Copyright (C) 2008, 2009, 2010, 2012 D. V. Wiebe
+.\" Copyright (C) 2008, 2009, 2010, 2012, 2013 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
@@ -13,7 +13,7 @@
.\" Texts. A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
-.TH gd_alter_bit 3 "26 July 2012" "Version 0.8.1" "GETDATA"
+.TH gd_alter_bit 3 "1 October 2013" "Version 0.8.6" "GETDATA"
.SH NAME
gd_alter_bit, gd_alter_carray, gd_alter_clincom, gd_alter_const,
gd_alter_cpolynom, gd_alter_crecip, gd_alter_divide, gd_alter_lincom,
@@ -167,7 +167,9 @@
.IR m ", " b ", " a ", " cm ", " cb ", or " ca ;
.TP
.B 0\fR:
-.IR spf ", " n_fields ", " numbits ", " cdividend ", or " dividend ;
+.IR spf ", " n_fields ", " numbits ", " cdividend ", " dividend ,
+or
+.IR array_len ;
.TP
.B -1\fR:
.IR bitnum " or " period ;
@@ -197,8 +199,17 @@
.I recode
is non-zero, the binary file associated with the
.B RAW
-field will be re-encoded to reflect the new field parameters.
+field will be re-encoded to reflect the new field parameters. In this case,
+the field's I/O pointer will be reset to the beginning-of-frame.
+If
+.BR gd_alter_carray ()
+is used to increase the length of a
+.B CARRAY
+field, the added elements will be uninitialised. Use
+.BR gd_put_carray_slice (3)
+or equivalent to initialise them.
+
See
.B NOTES
below for information on using
@@ -294,7 +305,7 @@
.BI "int " poly_ord ", const char *" in_fields ", const double *" ca );
.HP
.BI "int gd_alter_crecip(DIRFILE *" dirfile ", const char *" field_code ,
-.BI "const char *" in_field ", double " cdividend [2]);
+.BI "const char *" in_field ", const double " cdividend [2]);
.hy
.ad n
.PP
@@ -303,7 +314,7 @@
or
.IR ca
should have twice as many (purely real) elements, consisting of alternating
-real and imaginary parts for the complex data. For example,
+real and imaginary parts for the complex data. That is, for example,
.IR ca [0]
should be the real part of the first co-efficient,
.IR ca [1]
@@ -314,6 +325,22 @@
the imaginary part of the second co-efficient, and so on. Similarly, the
.I cdividend
parameter becomes a double precision array of length two.
+.PP
+For
+.BR gd_alter_clincom ()
+and
+.BR gd_alter_cpolynom (),
+these are simply different (but equivalent) declarations of the C99 function
+entry point. For
+.BR gd_alter_crecip (),
+however, a different entry point is needed (since the
+.I cdividend
+parameter is passed by reference instead of by value). In the interests of
+portability, the C89 version of
+.BR gd_alter_crecip ()
+is always available, and may be accessed as
+.BR gd_alter_crecip89 (),
+with the C89 prototype, in both the C99 and C89 APIs.
.SH SEE ALSO
.BR gd_alter_entry (3),
Modified: branches/getdata-0.8/man/gd_alter_encoding.3.in
===================================================================
--- branches/getdata-0.8/man/gd_alter_encoding.3.in 2014-12-05 21:16:00 UTC (rev 932)
+++ branches/getdata-0.8/man/gd_alter_encoding.3.in 2014-12-06 07:48:51 UTC (rev 933)
@@ -2,7 +2,7 @@
.\"
.\" @configure_input@
.\"
-.\" Copyright (C) 2008, 2009, 2010 D. V. Wiebe
+.\" Copyright (C) 2008, 2009, 2010, 2014 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
@@ -15,7 +15,7 @@
.\" Texts. A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
-.TH gd_alter_encoding 3 "20 July 2010" "Version 0.7.0" "GETDATA"
+.TH gd_alter_encoding 3 "16 October 2014" "Version 0.8.6" "GETDATA"
.SH NAME
gd_alter_encoding \(em modify the binary encoding of data in a dirfile
.SH SYNOPSIS
@@ -32,8 +32,8 @@
.BR gd_alter_encoding ()
function sets the binary encoding of the format specification fragment given by
.I fragment_index
-to
-.I byte_sex
+to the encoding specified by
+.I encoding
in the dirfile(5) database specified by
.IR dirfile .
The binary encoding of a fragment indicate the encoding of data stored in binary
@@ -45,13 +45,14 @@
fields is ignored.
The
-.I byte_sex
+.I encoding
argument should be one of the following:
.IP
.nh
.ad l
.BR GD_UNENCODED ,\~ GD_BZIP2_ENCODED ,\~ GD_GZIP_ENCODED ,\~
-.BR GD_LZMA_ENCODED ,\~ GD_SLIM_ENCODED ,\~ GD_TEXT_ENCODED .
+.BR GD_LZMA_ENCODED ,\~ GD_SLIM_ENCODED ,\~ GD_SIE_ENCODED ,\~
+.BR GD_TEXT_ENCODED .
.ad n
.hy
.PP
@@ -73,7 +74,11 @@
.B RAW
fields to account for the change in binary encoding. If the encoding of the
fragment is encoding insensitive, or if the data type is only one byte in
-size, no change is made. If
+size, no change is made. The I/O pointer of all affected
+.B RAW
+fields is reset to the beginning-of-frame.
+
+If
.I recode
is zero, affected binary files are left untouched.
Modified: branches/getdata-0.8/man/gd_alter_entry.3
===================================================================
--- branches/getdata-0.8/man/gd_alter_entry.3 2014-12-05 21:16:00 UTC (rev 932)
+++ branches/getdata-0.8/man/gd_alter_entry.3 2014-12-06 07:48:51 UTC (rev 933)
@@ -1,6 +1,6 @@
.\" gd_alter_entry.3. The gd_alter_entry man page.
.\"
-.\" Copyright (C) 2008, 2009, 2010, 2012 D. V. Wiebe
+.\" Copyright (C) 2008, 2009, 2010, 2012, 2013 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
@@ -13,7 +13,7 @@
.\" Texts. A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
-.TH gd_alter_entry 3 "26 July 2012" "Version 0.8.1" "GETDATA"
+.TH gd_alter_entry 3 "1 October 2013" "Version 0.8.6" "GETDATA"
.SH NAME
gd_alter_entry \(em modify the metadata of a dirfile field
.SH SYNOPSIS
@@ -112,21 +112,25 @@
and then create a new field of the desired type with
.BR 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 parameters, or
-the parameters
-.RI ( entry -> a ,\~ entry -> b ,\~ entry -> m ,\~ entry -> ca ,\~ entry -> cb ,
-.RI "or " entry -> cm )
-are NULL, the old values will be retained. Similarly, if
-.IR entry -> spf ", " entry -> n_fields ", or " entry -> numbits
-is zero, or if
-.IR entry -> bitnum
-is -1, or if
-.IR entry -> data_type ", or " entry -> const_type
-are equal to
-.BR GD_NULL ,
-these parameters will not be modified.
-
+Some entry members have special values which indicate no change should be
+made to the member. These special values are:
+.TP
+.B NULL\fR:
+any of the string members, also
+.IR m ", " b ", " a ", " cm ", " cb ", or " ca ;
+.TP
+.B 0\fR:
+.IR spf ", " n_fields ", " numbits ", " cdividend ", " dividend ", or " array_len ;
+.TP
+.B -1\fR:
+.IR bitnum " or " period ;
+.TP
+.B GD_NULL\fR:
+.IR data_type " or " const_type ;
+.TP
+.B GD_WINDOP_UNK\fR:
+.IR windop .
+.PP
All
.IR entry -> scalar
elements relevant for the given field type must be initialised to one of the
@@ -142,10 +146,10 @@
.IR entry -> scalar_ind
element should also be set.
.IP \(bu 4
-a pointer the empty string (""). In this case, no change is made to the field
-code for the corresponding field parameter: if one already existed, it is kept,
-otherwise the corresponding literal numerical parameter is used. If the value
-of the corresponding numerical
+a pointer to the empty string (""). In this case, no change is made to the
+field code for the corresponding field parameter: if one already existed, it is
+kept, otherwise the corresponding literal numerical parameter is used. If the
+value of the corresponding numerical
.I entry
member is the special value listed above indicating no change, no change is
made to the field parameter at all.
@@ -157,6 +161,12 @@
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.
+.PP
+If this function is used to increase the length of a
+.B CARRAY
+field, the added elements will be uninitialised. Use
+.BR gd_put_carray_slice (3)
+or equivalent to initialise them.
.SH RETURN VALUE
On success,
Modified: branches/getdata-0.8/man/gd_linterp_tablename.3
===================================================================
--- branches/getdata-0.8/man/gd_linterp_tablename.3 2014-12-05 21:16:00 UTC (rev 932)
+++ branches/getdata-0.8/man/gd_linterp_tablename.3 2014-12-06 07:48:51 UTC (rev 933)
@@ -1,6 +1,6 @@
.\" gd_linterp_tablename.3. The gd_linterp_tablename man page.
.\"
-.\" Copyright (C) 2012 D. V. Wiebe
+.\" Copyright (C) 2012, 2013 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
@@ -13,7 +13,7 @@
.\" Texts. A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
-.TH gd_linterp_tablename 3 "1 August 2012" "Version 0.8.1" "GETDATA"
+.TH gd_linterp_tablename 3 "10 December 2013" "Version 0.8.6" "GETDATA"
.SH NAME
gd_linterp_tablename \(em retrieve the pathname of a look-up table in a dirfile
.SH SYNOPSIS
@@ -21,7 +21,7 @@
.HP
.nh
.ad l
-.BI "const char *gd_linterp_tablename(DIRFILE *" dirfile ", const char"
+.BI "char *gd_linterp_tablename(DIRFILE *" dirfile ", const char"
.BI * field_code );
.hy
.ad n
@@ -51,9 +51,13 @@
.SH RETURN VALUE
On success,
.BR gd_linterp_tablename ()
-returns the full pathname of the LUT associated with the specified field. On
-error, NULL is returned and the dirfile error is set to a non-zero error value.
-Possible error values are:
+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.
@@ -88,4 +92,6 @@
.BR gd_error (3),
.BR gd_error_string (3),
.BR dirfile (5),
-.BR dirfile-format (5)
+.BR dirfile-format (5),
+.BR free (3),
+.BR malloc (3)
Modified: branches/getdata-0.8/man/gd_madd_bit.3
===================================================================
--- branches/getdata-0.8/man/gd_madd_bit.3 2014-12-05 21:16:00 UTC (rev 932)
+++ branches/getdata-0.8/man/gd_madd_bit.3 2014-12-06 07:48:51 UTC (rev 933)
@@ -1,6 +1,6 @@
.\" gd_madd_bit.3. The gd_madd_bit man page.
.\"
-.\" Copyright (C) 2008, 2009, 2010, 2012 D. V. Wiebe
+.\" Copyright (C) 2008, 2009, 2010, 2012, 2013 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
@@ -13,7 +13,7 @@
.\" Texts. A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
-.TH gd_madd_bit 3 "1 April 2012" "Version 0.8.0" "GETDATA"
+.TH gd_madd_bit 3 "30 September 2013" "Version 0.8.6" "GETDATA"
.SH NAME
gd_madd_bit, gd_madd_carray, gd_madd_clincom, gd_madd_const, gd_madd_cpolynom,
gd_madd_crecip, gd_madd_divide, gd_madd_lincom, gd_madd_linterp,
@@ -283,7 +283,7 @@
or
.IR ca
should have twice as many (purely real) elements, consisting of alternating
-real and imaginary parts for the complex data. For example,
+real and imaginary parts for the complex data. That is, for example,
.IR ca [0]
should be the real part of the first co-efficient,
.IR ca [1]
@@ -294,6 +294,22 @@
the imaginary part of the second co-efficient, and so on. Similarly, the
.I cdividend
parameter becomes a double precision array of length two.
+.PP
+For
+.BR gd_madd_clincom ()
+and
+.BR gd_madd_cpolynom (),
+these are simply different (but equivalent) declarations of the C99 function
+entry point. For
+.BR gd_madd_crecip (),
+however, a different entry point is needed (since the
+.I cdividend
+parameter is passed by reference instead of by value). In the interests of
+portability, the C89 version of
+.BR gd_madd_crecip ()
+is always available, and may be accessed as
+.BR gd_madd_crecip89 (),
+with the C89 prototype, in both the C99 and C89 APIs.
.SH SEE ALSO
.BR gd_add_bit (3),
Modified: branches/getdata-0.8/man/gd_naliases.3
===================================================================
--- branches/getdata-0.8/man/gd_naliases.3 2014-12-05 21:16:00 UTC (rev 932)
+++ branches/getdata-0.8/man/gd_naliases.3 2014-12-06 07:48:51 UTC (rev 933)
@@ -1,6 +1,6 @@
.\" gd_naliases.3. The gd_naliases man page.
.\"
-.\" Copyright (C) 2012 D. V. Wiebe
+.\" Copyright (C) 2012, 2013 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
@@ -13,7 +13,7 @@
.\" Texts. A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
-.TH gd_naliases 3 "1 January 2012" "Version 0.8.0" "GETDATA"
+.TH gd_naliases 3 "1 October 2013" "Version 0.8.6" "GETDATA"
.SH NAME
gd_naliases \(em report the number of aliases of a field in a dirfile
.SH SYNOPSIS
@@ -40,9 +40,9 @@
.SH RETURN VALUE
Upon successful completion,
.BR gd_naliases ()
-returns the number of vector fields in the dirfile. If successful, this count
-will be at least one. On error, it returns zero and sets the dirfile error
-to a non-zero error value. Possible error values are:
+returns the number of aliases of the specified field code in the dirfile. If
+successful, this count will be at least one. On error, it returns zero and
+sets the dirfile error to a non-zero error value. Possible error values are:
.TP 8
.B GD_E_BAD_CODE
The supplied field code was not found in the database.
Modified: branches/getdata-0.8/man/gd_raw_filename.3
===================================================================
--- branches/getdata-0.8/man/gd_raw_filename.3 2014-12-05 21:16:00 UTC (rev 932)
+++ branches/getdata-0.8/man/gd_raw_filename.3 2014-12-06 07:48:51 UTC (rev 933)
@@ -1,6 +1,6 @@
.\" gd_raw_filename.3. The gd_raw_filename man page.
.\"
-.\" Copyright (C) 2008, 2009, 2010 D. V. Wiebe
+.\" Copyright (C) 2008, 2009, 2010, 2013 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
@@ -13,7 +13,7 @@
.\" Texts. A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
-.TH gd_raw_filename 3 "16 July 2010" "Version 0.7.0" "GETDATA"
+.TH gd_raw_filename 3 "10 December 2013" "Version 0.8.6" "GETDATA"
.SH NAME
gd_raw_filename \(em retrieve the pathname of a binary file in a dirfile
.SH SYNOPSIS
@@ -21,14 +21,14 @@
.HP
.nh
.ad l
-.BI "const char *gd_raw_filename(DIRFILE *" dirfile ", const char"
+.BI "char *gd_raw_filename(DIRFILE *" dirfile ", const char"
.BI * field_code );
.hy
.ad n
.SH DESCRIPTION
The
.BR gd_raw_filename ()
-function retrieves the pathname of the file backing the
+function reports the pathname of the file backing the
.B RAW
field specified by
.I field_code
@@ -42,8 +42,12 @@
On success,
.BR gd_raw_filename ()
returns the full pathname of the binary file associated with the specified
-field. On error, NULL is returned and the dirfile error is set to a non-zero
-error value. Possible error values are:
+field in buffer allocated by
+.BR malloc (3).
+The returned pointer should be passed to
+.BR free (3)
+once the caller no longer needs it. 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.
@@ -83,4 +87,6 @@
.BR gd_error_string (3),
.BR dirfile (5),
.BR dirfile-encoding (5),
-.BR dirfile-format (5)
+.BR dirfile-format (5),
+.BR free (3)
+.BR malloc (3)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
