From: Nikos Mavrogiannopoulos Date: Tue, 22 Nov 2011 22:11:21 +0000 (+0100) Subject: Separated API reference to header files in the texi manual. X-Git-Tag: gnutls_3_0_9~48 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cc131a99593812dd0dddd78f802b0f67adadf482;p=thirdparty%2Fgnutls.git Separated API reference to header files in the texi manual. --- diff --git a/.gitignore b/.gitignore index 92174c1505..5b8b7522ec 100644 --- a/.gitignore +++ b/.gitignore @@ -71,9 +71,14 @@ doc/examples/ex-serv-psk doc/examples/ex-serv-srp doc/examples/ex-serv1 doc/examples/libexamples.la -doc/extra-api.texi doc/extra.c.texi doc/gnutls-api.texi +doc/abstract-api.texi +doc/pkcs11-api.texi +doc/pkcs12-api.texi +doc/dtls-api.texi +doc/crypto-api.texi +doc/compat-api.texi doc/gnutls-extra-api.texi doc/gnutls-guile.html doc/gnutls.aux diff --git a/doc/Makefile.am b/doc/Makefile.am index 9907dafa50..609cac1662 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -90,42 +90,112 @@ MAINTAINERCLEANFILES = # Generated texinfos. gnutls_TEXINFOS += gnutls-api.texi \ - x509-api.texi pgp-api.texi + x509-api.texi pgp-api.texi pkcs12-api.texi pkcs11-api.texi \ + abstract-api.texi compat-api.texi dtls-api.texi crypto-api.texi + MAINTAINERCLEANFILES += gnutls-api.texi \ - x509-api.texi pgp-api.texi + x509-api.texi pgp-api.texi pkcs12-api.texi pkcs11-api.texi \ + abstract-api.texi compat-api.texi dtls-api.texi crypto-api.texi -gnutls-api.texi: $(srcdir)/../lib/*.c $(srcdir)/../lib/ext/*.c $(srcdir)/../lib/auth/*.c $(srcdir)/../lib/algorithms/*.c +gnutls-api.texi: $(top_srcdir)/lib/includes/gnutls/gnutls.h.in echo "" > $@-tmp - for i in $^; do \ + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/gnutls.h.in|sort|uniq`; do \ echo -n "Creating documentation for file $$i... " && \ - $(srcdir)/scripts/gdoc -texinfo $$i >> $@-tmp && \ + $(srcdir)/scripts/gdoc -texinfo \ + -function $$i \ + $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*/*.c >> $@-tmp 2>/dev/null && \ echo "ok"; \ done - $(srcdir)/scripts/sort2.pl < $@-tmp > $@-tmp2 - rm -f $@-tmp - mv -f $@-tmp2 $@ + mv -f $@-tmp $@ -x509-api.texi: $(srcdir)/../lib/x509/*.c +x509-api.texi: $(top_srcdir)/lib/includes/gnutls/x509.h echo "" > $@-tmp - for i in $^; do \ + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/x509.h|sort|uniq`; do \ echo -n "Creating documentation for file $$i... " && \ - $(srcdir)/scripts/gdoc -texinfo $$i >> $@-tmp && \ + $(srcdir)/scripts/gdoc -texinfo \ + -function $$i \ + $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*/*.c >> $@-tmp 2>/dev/null && \ echo "ok"; \ done - $(srcdir)/scripts/sort2.pl < $@-tmp > $@-tmp2 - rm -f $@-tmp - mv -f $@-tmp2 $@ + mv -f $@-tmp $@ -pgp-api.texi: $(srcdir)/../lib/openpgp/*.c +pgp-api.texi: $(top_srcdir)/lib/includes/gnutls/openpgp.h echo "" > $@-tmp - for i in $^; do \ + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/openpgp.h|sort|uniq`; do \ echo -n "Creating documentation for file $$i... " && \ - $(srcdir)/scripts/gdoc -texinfo $$i >> $@-tmp && \ + $(srcdir)/scripts/gdoc -texinfo \ + -function $$i \ + $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*/*.c >> $@-tmp 2>/dev/null && \ + echo "ok"; \ + done + mv -f $@-tmp $@ + + +pkcs12-api.texi: $(top_srcdir)/lib/includes/gnutls/pkcs12.h + echo "" > $@-tmp + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/pkcs12.h|sort|uniq`; do \ + echo -n "Creating documentation for file $$i... " && \ + $(srcdir)/scripts/gdoc -texinfo \ + -function $$i \ + $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*/*.c >> $@-tmp 2>/dev/null && \ + echo "ok"; \ + done + mv -f $@-tmp $@ + +pkcs11-api.texi: $(top_srcdir)/lib/includes/gnutls/pkcs11.h + echo "" > $@-tmp + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/pkcs11.h|sort|uniq`; do \ + echo -n "Creating documentation for file $$i... " && \ + $(srcdir)/scripts/gdoc -texinfo \ + -function $$i \ + $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*/*.c >> $@-tmp 2>/dev/null && \ echo "ok"; \ done - $(srcdir)/scripts/sort2.pl < $@-tmp > $@-tmp2 - rm -f $@-tmp - mv -f $@-tmp2 $@ + mv -f $@-tmp $@ + +abstract-api.texi: $(top_srcdir)/lib/includes/gnutls/abstract.h + echo "" > $@-tmp + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/abstract.h|sort|uniq`; do \ + echo -n "Creating documentation for file $$i... " && \ + $(srcdir)/scripts/gdoc -texinfo \ + -function $$i \ + $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*/*.c >> $@-tmp 2>/dev/null && \ + echo "ok"; \ + done + mv -f $@-tmp $@ + +compat-api.texi: $(top_srcdir)/lib/includes/gnutls/compat.h + echo "" > $@-tmp + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/compat.h|sort|uniq`; do \ + echo -n "Creating documentation for file $$i... " && \ + $(srcdir)/scripts/gdoc -texinfo \ + -function $$i \ + $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*/*.c >> $@-tmp 2>/dev/null && \ + echo "ok"; \ + done + mv -f $@-tmp $@ + +dtls-api.texi: $(top_srcdir)/lib/includes/gnutls/dtls.h + echo "" > $@-tmp + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/dtls.h|sort|uniq`; do \ + echo -n "Creating documentation for file $$i... " && \ + $(srcdir)/scripts/gdoc -texinfo \ + -function $$i \ + $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*/*.c >> $@-tmp 2>/dev/null && \ + echo "ok"; \ + done + mv -f $@-tmp $@ + +crypto-api.texi: $(top_srcdir)/lib/includes/gnutls/crypto.h + echo "" > $@-tmp + for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/crypto.h|sort|uniq`; do \ + echo -n "Creating documentation for file $$i... " && \ + $(srcdir)/scripts/gdoc -texinfo \ + -function $$i \ + $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*/*.c >> $@-tmp 2>/dev/null && \ + echo "ok"; \ + done + mv -f $@-tmp $@ # Generated texinfos. diff --git a/doc/cha-functions.texi b/doc/cha-functions.texi index 4df9a598b8..1835fcf97d 100644 --- a/doc/cha-functions.texi +++ b/doc/cha-functions.texi @@ -1,23 +1,37 @@ -@node Function reference -@appendix Function Reference -@cindex function reference +@node API reference +@appendix API reference +@cindex API reference @menu -* Core functions:: -* X509 certificate functions:: -* OpenPGP functions:: +* Core TLS API:: +* Datagram TLS API:: +* X509 certificate API:: +* OpenPGP API:: +* PKCS 12 API:: +* PKCS 11 API:: +* Abstract key API:: +* Cryptographic API:: +* Compatibility API:: @end menu -@node Core functions -@section Core Functions +@node Core TLS API +@section Core TLS API The prototypes for the following functions lie in @file{gnutls/gnutls.h}. @include gnutls-api.texi -@node X509 certificate functions -@section @acronym{X.509} Certificate Functions +@node Datagram TLS API +@section Datagram TLS API + +The prototypes for the following functions lie in +@file{gnutls/dtls.h}. + +@include dtls-api.texi + +@node X509 certificate API +@section @acronym{X.509} certificate API @cindex X.509 Functions The following functions are to be used for @acronym{X.509} certificate handling. @@ -25,9 +39,9 @@ Their prototypes lie in @file{gnutls/x509.h}. @include x509-api.texi -@node OpenPGP functions -@section @acronym{OpenPGP} Functions -@cindex OpenPGP functions +@node OpenPGP API +@section @acronym{OpenPGP} API +@cindex OpenPGP API The following functions are to be used for @acronym{OpenPGP} certificate handling. Their prototypes lie in @@ -35,3 +49,42 @@ certificate handling. Their prototypes lie in @include pgp-api.texi +@node PKCS 12 API +@section PKCS 12 API + +The following functions are to be used for PKCS 12 handling. +Their prototypes lie in @file{gnutls/pkcs12.h}. + +@include pkcs12-api.texi + +@node PKCS 11 API +@section Hardware token via PKCS 11 API + +The following functions are to be used for PKCS 11 handling. +Their prototypes lie in @file{gnutls/pkcs11.h}. + +@include pkcs11-api.texi + +@node Abstract key API +@section Abstract key API + +The following functions are to be used for abstract key handling. +Their prototypes lie in @file{gnutls/abstract.h}. + +@include abstract-api.texi + +@node Cryptographic API +@section Cryptographic API + +The following functions are to be used for low-level cryptographic operations. +Their prototypes lie in @file{gnutls/crypto.h}. + +@include crypto-api.texi + +@node Compatibility API +@section Compatibility API + +The following functions are carried over from old GnuTLS released. They might be removed at a later version. +Their prototypes lie in @file{gnutls/compat.h}. + +@include compat-api.texi diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi index d9cba2577b..0699c53ad3 100644 --- a/doc/cha-gtls-app.texi +++ b/doc/cha-gtls-app.texi @@ -169,9 +169,8 @@ data to the transport layer. Other callback functions may require more complicated input and data to be allocated. Such an example is @funcref{gnutls_srp_set_server_credentials_function}. -All callbacks should allocate and free memory using the functions shown below. - -@showfuncB{gnutls_malloc,gnutls_free} +All callbacks should allocate and free memory using +@funcintref{gnutls_malloc} and @funcintref{gnutls_free}. @node Preparation diff --git a/doc/gnutls.texi b/doc/gnutls.texi index 8f4e13fc18..056297fa53 100644 --- a/doc/gnutls.texi +++ b/doc/gnutls.texi @@ -158,7 +158,7 @@ Documentation License''. * Internal architecture of GnuTLS:: * Support:: * Error codes:: -* Function reference:: +* API reference:: * Supported ciphersuites in GnuTLS:: * Copying Information:: * Concept Index:: diff --git a/doc/scripts/gdoc b/doc/scripts/gdoc index 8e05ce6e51..902829a508 100755 --- a/doc/scripts/gdoc +++ b/doc/scripts/gdoc @@ -136,7 +136,7 @@ use POSIX qw(strftime); # match expressions used to find embedded type information $type_constant = "\\\%([A-Za-z0-9_]+)"; $type_func = "([A-Za-z0-9_]+\\(\\))"; -$type_param = "\\s\\\@([A-Za-z0-9_]+)"; +$type_param = '\@([A-Za-z0-9_]+)\s*'; $type_struct = "\\\#([A-Za-z0-9_]+)"; $type_env = "(\\\$[A-Za-z0-9_]+)"; diff --git a/lib/gnutls_state.c b/lib/gnutls_state.c index 3c12508cc5..3fcd803ad7 100644 --- a/lib/gnutls_state.c +++ b/lib/gnutls_state.c @@ -1040,7 +1040,7 @@ gnutls_prf_raw (gnutls_session_t session, * generated output is strongly connected to some additional data * (e.g., a string used in user authentication). * - * The output is placed in *@OUT, which must be pre-allocated. + * The output is placed in @out, which must be pre-allocated. * * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ diff --git a/lib/includes/gnutls/gnutls.h.in b/lib/includes/gnutls/gnutls.h.in index f6395e203e..072e0163a3 100644 --- a/lib/includes/gnutls/gnutls.h.in +++ b/lib/includes/gnutls/gnutls.h.in @@ -1338,15 +1338,15 @@ gnutls_ecc_curve_t gnutls_ecc_curve_get(gnutls_session_t session); generator, gnutls_datum_t * prime); void - gnutls_srp_set_server_credentials_function - (gnutls_srp_server_credentials_t cred, + gnutls_srp_set_server_credentials_function ( + gnutls_srp_server_credentials_t cred, gnutls_srp_server_credentials_function * func); typedef int gnutls_srp_client_credentials_function (gnutls_session_t, char **, char **); void - gnutls_srp_set_client_credentials_function - (gnutls_srp_client_credentials_t cred, + gnutls_srp_set_client_credentials_function ( + gnutls_srp_client_credentials_t cred, gnutls_srp_client_credentials_function * func); int gnutls_srp_base64_encode (const gnutls_datum_t * data, char *result, @@ -1407,16 +1407,16 @@ gnutls_ecc_curve_t gnutls_ecc_curve_get(gnutls_session_t session); const char *username, gnutls_datum_t * key); void - gnutls_psk_set_server_credentials_function - (gnutls_psk_server_credentials_t cred, + gnutls_psk_set_server_credentials_function ( + gnutls_psk_server_credentials_t cred, gnutls_psk_server_credentials_function * func); typedef int gnutls_psk_client_credentials_function (gnutls_session_t, char **username, gnutls_datum_t * key); void - gnutls_psk_set_client_credentials_function - (gnutls_psk_client_credentials_t cred, + gnutls_psk_set_client_credentials_function ( + gnutls_psk_client_credentials_t cred, gnutls_psk_client_credentials_function * func); int gnutls_hex_encode (const gnutls_datum_t * data, char *result, @@ -1442,7 +1442,7 @@ gnutls_ecc_curve_t gnutls_ecc_curve_get(gnutls_session_t session); * @GNUTLS_SAN_OTHERNAME: OtherName SAN. * @GNUTLS_SAN_DN: DN SAN. * @GNUTLS_SAN_OTHERNAME_XMPP: Virtual SAN, used by - * gnutls_x509_crt_get_subject_alt_othername_oid(). + * gnutls_x509_crt_get_subject_alt_othername_oid. * * Enumeration of different subject alternative names types. */ @@ -1456,7 +1456,7 @@ gnutls_ecc_curve_t gnutls_ecc_curve_get(gnutls_session_t session); GNUTLS_SAN_DN = 6, /* The following are "virtual" subject alternative name types, in that they are represented by an otherName value and an OID. - Used by gnutls_x509_crt_get_subject_alt_othername_oid(). */ + Used by gnutls_x509_crt_get_subject_alt_othername_oid. */ GNUTLS_SAN_OTHERNAME_XMPP = 1000 } gnutls_x509_subject_alt_name_t; @@ -1553,8 +1553,8 @@ gnutls_ecc_curve_t gnutls_ecc_curve_get(gnutls_session_t session); gnutls_retr2_st *); - void gnutls_certificate_set_retrieve_function - (gnutls_certificate_credentials_t cred, + void gnutls_certificate_set_retrieve_function ( + gnutls_certificate_credentials_t cred, gnutls_certificate_retrieve_function * func); typedef int gnutls_certificate_verify_function (gnutls_session_t); diff --git a/lib/includes/gnutls/openpgp.h b/lib/includes/gnutls/openpgp.h index c3cedf8887..f5c456dab9 100644 --- a/lib/includes/gnutls/openpgp.h +++ b/lib/includes/gnutls/openpgp.h @@ -345,12 +345,12 @@ extern "C" const char *subkey_id, gnutls_openpgp_crt_fmt_t format); - int gnutls_certificate_set_openpgp_keyring_mem - (gnutls_certificate_credentials_t c, const unsigned char *data, + int gnutls_certificate_set_openpgp_keyring_mem ( + gnutls_certificate_credentials_t c, const unsigned char *data, size_t dlen, gnutls_openpgp_crt_fmt_t format); - int gnutls_certificate_set_openpgp_keyring_file - (gnutls_certificate_credentials_t c, const char *file, + int gnutls_certificate_set_openpgp_keyring_file ( + gnutls_certificate_credentials_t c, const char *file, gnutls_openpgp_crt_fmt_t format); #ifdef __cplusplus