From: Rich Salz Date: Tue, 7 Jun 2016 17:08:20 +0000 (-0400) Subject: Nit about pod filenames X-Git-Tag: OpenSSL_1_1_0-pre6~523 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=fbba5d113f1294992cd99643c79860df8f64015a;p=oweals%2Fopenssl.git Nit about pod filenames The asdf.pod filename must have asdf in its NAME section. also check for names existing as a different filename (via Levitte) Reviewed-by: Richard Levitte Reviewed-by: Viktor Dukhovni --- diff --git a/doc/crypto/X509_PUBKEY.pod b/doc/crypto/X509_PUBKEY.pod deleted file mode 100644 index 0e8a14abb5..0000000000 --- a/doc/crypto/X509_PUBKEY.pod +++ /dev/null @@ -1,120 +0,0 @@ -=pod - -=head1 NAME - -X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_set, X509_PUBKEY_get0, -X509_PUBKEY_get, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp, -i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param, -X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions - -=head1 SYNOPSIS - - #include - - X509_PUBKEY *X509_PUBKEY_new(void); - void X509_PUBKEY_free(X509_PUBKEY *a); - - int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey); - EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key); - EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key); - - EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length); - int i2d_PUBKEY(EVP_PKEY *a, unsigned char **pp); - - EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a); - EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a); - - int i2d_PUBKEY_fp(FILE *fp, EVP_PKEY *pkey); - int i2d_PUBKEY_bio(BIO *bp, EVP_PKEY *pkey); - - int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj, - int ptype, void *pval, - unsigned char *penc, int penclen); - int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg, - const unsigned char **pk, int *ppklen, - X509_ALGOR **pa, X509_PUBKEY *pub); - -=head1 DESCRIPTION - -The B structure represents the ASN.1 B -structure defined in RFC5280 and used in certificates and certificate requests. - -X509_PUBKEY_new() allocates and initializes an B structure. - -X509_PUBKEY_free() frees up B structure B. If B is NULL -nothing is done. - -X509_PUBKEY_set() sets the public key in B<*x> to the public key contained -in the B structure B. If B<*x> is not NULL any existing -public key structure will be freed. - -X509_PUBKEY_get0() returns the public key contained in B. The returned -value is an internal pointer which B be freed after use. - -X509_PUBKEY_get() is similar to X509_PUBKEY_get0() except the reference -count on the returned key is incremented so it B be freed using -EVP_PKEY_free() after use. - -d2i_PUBKEY() and i2d_PUBKEY() decode and encode an B structure -using B format. They otherise follow the conventions of -other ASN.1 functions such as d2i_X509(). - -d2i_PUBKEY_bio(), d2i_PUBKEY_fp(), i2d_PUBKEY_bio() and i2d_PUBKEY_fp() are -similar to d2i_PUBKEY() and i2d_PUBKEY() except they decode or encode using a -B or B pointer. - -X509_PUBKEY_set0_param() sets the public key parameters of B. The -OID associated with the algorithm is set to B. The type of the -algorithm parameters is set to B using the structure B. -The encoding of the public key itself is set to the B -bytes contained in buffer B. On success ownership of all the supplied -parameters is passed to B so they must not be freed after the -call. - -X509_PUBKEY_get0_param() retrieves the public key parameters from B, -B<*ppkalg> is set to the associated OID and the encoding consists of -B<*ppklen> bytes at B<*pk>, B<*pa> is set to the associated -AlgorithmIdentifier for the public key. If the value of any of these -parameters is not required it can be set to B. All of the -retrieved pointers are internal and must not be freed after the -call. - -=head1 NOTES - -The B functions can be used to encode and decode public keys -in a standard format. - -In many cases applications will not call the B functions -directly: they will instead call wrapper functions such as X509_get0_pubkey(). - -=head1 RETURN VALUES - -If the allocation fails, X509_PUBKEY_new() returns B and sets an error -code that can be obtained by L. - -Otherwise it returns a pointer to the newly allocated structure. - -X509_PUBKEY_free() does not return a value. - -X509_PUBKEY_get0() and X509_PUBKEY_get() return a pointer to an B -structure or B if an error occurs. - -X509_PUBKEY_set(), X509_PUBKEY_set0_param() and X509_PUBKEY_get0_param() -return 1 for success and 0 if an error occurred. - -=head1 SEE ALSO - -L, -L, -L, - -=head1 COPYRIGHT - -Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/crypto/X509_PUBKEY_new.pod b/doc/crypto/X509_PUBKEY_new.pod new file mode 100644 index 0000000000..0e8a14abb5 --- /dev/null +++ b/doc/crypto/X509_PUBKEY_new.pod @@ -0,0 +1,120 @@ +=pod + +=head1 NAME + +X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_set, X509_PUBKEY_get0, +X509_PUBKEY_get, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp, +i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param, +X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions + +=head1 SYNOPSIS + + #include + + X509_PUBKEY *X509_PUBKEY_new(void); + void X509_PUBKEY_free(X509_PUBKEY *a); + + int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey); + EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key); + EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key); + + EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length); + int i2d_PUBKEY(EVP_PKEY *a, unsigned char **pp); + + EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a); + EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a); + + int i2d_PUBKEY_fp(FILE *fp, EVP_PKEY *pkey); + int i2d_PUBKEY_bio(BIO *bp, EVP_PKEY *pkey); + + int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj, + int ptype, void *pval, + unsigned char *penc, int penclen); + int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg, + const unsigned char **pk, int *ppklen, + X509_ALGOR **pa, X509_PUBKEY *pub); + +=head1 DESCRIPTION + +The B structure represents the ASN.1 B +structure defined in RFC5280 and used in certificates and certificate requests. + +X509_PUBKEY_new() allocates and initializes an B structure. + +X509_PUBKEY_free() frees up B structure B. If B is NULL +nothing is done. + +X509_PUBKEY_set() sets the public key in B<*x> to the public key contained +in the B structure B. If B<*x> is not NULL any existing +public key structure will be freed. + +X509_PUBKEY_get0() returns the public key contained in B. The returned +value is an internal pointer which B be freed after use. + +X509_PUBKEY_get() is similar to X509_PUBKEY_get0() except the reference +count on the returned key is incremented so it B be freed using +EVP_PKEY_free() after use. + +d2i_PUBKEY() and i2d_PUBKEY() decode and encode an B structure +using B format. They otherise follow the conventions of +other ASN.1 functions such as d2i_X509(). + +d2i_PUBKEY_bio(), d2i_PUBKEY_fp(), i2d_PUBKEY_bio() and i2d_PUBKEY_fp() are +similar to d2i_PUBKEY() and i2d_PUBKEY() except they decode or encode using a +B or B pointer. + +X509_PUBKEY_set0_param() sets the public key parameters of B. The +OID associated with the algorithm is set to B. The type of the +algorithm parameters is set to B using the structure B. +The encoding of the public key itself is set to the B +bytes contained in buffer B. On success ownership of all the supplied +parameters is passed to B so they must not be freed after the +call. + +X509_PUBKEY_get0_param() retrieves the public key parameters from B, +B<*ppkalg> is set to the associated OID and the encoding consists of +B<*ppklen> bytes at B<*pk>, B<*pa> is set to the associated +AlgorithmIdentifier for the public key. If the value of any of these +parameters is not required it can be set to B. All of the +retrieved pointers are internal and must not be freed after the +call. + +=head1 NOTES + +The B functions can be used to encode and decode public keys +in a standard format. + +In many cases applications will not call the B functions +directly: they will instead call wrapper functions such as X509_get0_pubkey(). + +=head1 RETURN VALUES + +If the allocation fails, X509_PUBKEY_new() returns B and sets an error +code that can be obtained by L. + +Otherwise it returns a pointer to the newly allocated structure. + +X509_PUBKEY_free() does not return a value. + +X509_PUBKEY_get0() and X509_PUBKEY_get() return a pointer to an B +structure or B if an error occurs. + +X509_PUBKEY_set(), X509_PUBKEY_set0_param() and X509_PUBKEY_get0_param() +return 1 for success and 0 if an error occurred. + +=head1 SEE ALSO + +L, +L, +L, + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/util/find-doc-nits.pl b/util/find-doc-nits.pl index b0fab95353..59647f9294 100755 --- a/util/find-doc-nits.pl +++ b/util/find-doc-nits.pl @@ -48,10 +48,24 @@ sub name_synopsis() $tmp =~ tr/\n/ /; $tmp =~ s/-.*//g; $tmp =~ s/,//g; + + my $dirname = dirname($filename); + my $simplename = basename($filename); + $simplename =~ s/.pod$//; + my $foundfilename = 0; + my %foundfilenames = (); my %names; foreach my $n ( split ' ', $tmp ) { $names{$n} = 1; + $foundfilename++ if $n eq $simplename; + $foundfilenames{$n} = 1 + if -f "$dirname/$n.pod" && $n ne $simplename; } + print "$id the following exist as other .pod files:\n", + join(" ", sort keys %foundfilenames), "\n" + if %foundfilenames; + print "$id $simplename (filename) missing from NAME section\n", + unless $foundfilename; # Find all functions in SYNOPSIS return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;