diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-12-03 15:18:07 +0100 |
---|---|---|
committer | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2022-01-03 17:56:57 +0100 |
commit | 4623700d4eaaa250b49032768be2e97a147f3a1e (patch) | |
tree | 21b1c2bd7a7a4806cf90b3793b76cc6045a996d1 | |
parent | e5050aa1bbce84e359bfd35de60dd745627e8d41 (diff) |
OBJ_obj2txt(): fix off-by-one documentation of the result
This backports the doc improvements of #17188.
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(cherry picked from commit e36d10925396b6519e1abd338e1ef62cd5b1c9e6)
-rw-r--r-- | doc/man3/OBJ_nid2obj.pod | 32 |
1 files changed, 16 insertions, 16 deletions
diff --git a/doc/man3/OBJ_nid2obj.pod b/doc/man3/OBJ_nid2obj.pod index 74379ad817..81e57154f1 100644 --- a/doc/man3/OBJ_nid2obj.pod +++ b/doc/man3/OBJ_nid2obj.pod @@ -68,13 +68,15 @@ If I<no_name> is 0 then long names and short names will be interpreted as well as numerical forms. If I<no_name> is 1 only the numerical form is acceptable. -OBJ_obj2txt() converts the B<ASN1_OBJECT> B<a> into a textual representation. -The representation is written as a null terminated string to B<buf> -at most B<buf_len> bytes are written, truncating the result if necessary. -The total amount of space required is returned. If B<no_name> is 0 then -if the object has a long or short name then that will be used, otherwise -the numerical form will be used. If B<no_name> is 1 then the numerical -form will always be used. +OBJ_obj2txt() converts the B<ASN1_OBJECT> I<a> into a textual representation. +Unless I<buf> is NULL, +the representation is written as a NUL-terminated string to I<buf>, where +at most I<buf_len> bytes are written, truncating the result if necessary. +In any case it returns the total string length, excluding the NUL character, +required for non-truncated representation, or -1 on error. +If I<no_name> is 0 then if the object has a long or short name +then that will be used, otherwise the numerical form will be used. +If I<no_name> is 1 then the numerical form will always be used. i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the I<no_name> set to zero. @@ -141,6 +143,13 @@ on error. OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return a NID or B<NID_undef> on error. +OBJ_add_sigid() returns 1 on success or 0 on error. + +i2t_ASN1_OBJECT() an OBJ_obj2txt() return -1 on error. +On success, they return the length of the string written to I<buf> if I<buf> is +not NULL and I<buf_len> is big enough, otherwise the total string length. +Note that this does not count the trailing NUL character. + =head1 EXAMPLES Create an object for B<commonName>: @@ -161,15 +170,6 @@ Create a new object directly: obj = OBJ_txt2obj("1.2.3.4", 1); -=head1 BUGS - -OBJ_obj2txt() is awkward and messy to use: it doesn't follow the -convention of other OpenSSL functions where the buffer can be set -to B<NULL> to determine the amount of data that should be written. -Instead B<buf> must point to a valid buffer and B<buf_len> should -be set to a positive value. A buffer length of 80 should be more -than enough to handle any OID encountered in practice. - =head1 SEE ALSO L<ERR_get_error(3)> |