root
/
openssl
mirror of https://github.com/openssl/openssl.git
1
0
Fork 0
Code Issues Actions 7 Packages Projects Releases Wiki Activity

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)
This commit is contained in:
Dr. David von Oheimb 2021-12-03 15:18:07 +01:00
parent e5050aa1bb
commit 4623700d4e
1 changed files with 16 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
doc/man3/OBJ_nid2obj.pod
View File

@ -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)>