Commit 91da5e77 authored by Rich Salz's avatar Rich Salz
Browse files

Replace all #define's in pod pages. 



Function-like macros are replaced with prototypes and a note
that they are implemented as macros.  Constants are just
referenced in-line in the text.

Tweak BIO_TYPE_... documentation.

Also fix RT4592.

Reviewed-by: default avatarMatt Caswell <matt@openssl.org>
parent 07aaab39

doc/crypto/ASYNC_start_job.pod

+1 −3
Original line number Diff line number Diff line
@@ -182,8 +182,6 @@ The following example demonstrates how to use most of the core async APIs: 
 #include <openssl/async.h>

 #include <openssl/crypto.h>



 #define WAIT_SIGNAL_CHAR   'X'



 int unique = 0;



 void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw)
@@ -200,7 +198,7 @@ The following example demonstrates how to use most of the core async APIs: 
     unsigned char *msg;

     int pipefds[2] = {0, 0};

     OSSL_ASYNC_FD *wptr;

     char buf = WAIT_SIGNAL_CHAR;

     char buf = 'X';



     currjob = ASYNC_get_current_job();

     if (currjob != NULL) {

doc/crypto/BIO_ctrl.pod

+9 −9
Original line number Diff line number Diff line
@@ -11,8 +11,10 @@ BIO_get_info_callback, BIO_set_info_callback - BIO control operations 


 #include <openssl/bio.h>



 typedef void (*bio_info_cb)(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);



 long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);

 long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));

 long BIO_callback_ctrl(BIO *b, int cmd, bio_info_cb cb);

 char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);

 long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
@@ -31,8 +33,6 @@ BIO_get_info_callback, BIO_set_info_callback - BIO control operations 
 int BIO_get_info_callback(BIO *b, bio_info_cb **cbp);

 int BIO_set_info_callback(BIO *b, bio_info_cb *cb);



 typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);



=head1 DESCRIPTION



BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl()

doc/crypto/BIO_f_buffer.pod

+10 −7
Original line number Diff line number Diff line
@@ -7,7 +7,8 @@ BIO_set_read_buffer_size, 
BIO_set_write_buffer_size,

BIO_set_buffer_size,

BIO_set_buffer_read_data,

BIO_f_buffer - buffering BIO

BIO_f_buffer

- buffering BIO



=head1 SYNOPSIS
@@ -15,11 +16,11 @@ BIO_f_buffer - buffering BIO 


 const BIO_METHOD *BIO_f_buffer(void);



 #define BIO_get_buffer_num_lines(b)

 #define BIO_set_read_buffer_size(b,size)

 #define BIO_set_write_buffer_size(b,size)

 #define BIO_set_buffer_size(b,size)

 #define BIO_set_buffer_read_data(b,buf,num)

 long BIO_get_buffer_num_lines(BIO *b);

 long BIO_set_read_buffer_size(BIO *b, long size);

 long BIO_set_write_buffer_size(BIO *b, long size);

 long BIO_set_buffer_size(BIO *b, long size);

 long BIO_set_buffer_read_data(BIO *b, void *buf, long num);



=head1 DESCRIPTION
@@ -46,6 +47,8 @@ is expanded. 


=head1 NOTES



These functions, other than BIO_f_buffer(), are implemented as macros.



Buffering BIOs implement BIO_gets() by using BIO_read() operations on the

next BIO in the chain. By prepending a buffering BIO to a chain it is therefore

possible to provide BIO_gets() functionality if the following BIOs do not

doc/crypto/BIO_f_ssl.pod

+14 −13
Original line number Diff line number Diff line
@@ -18,15 +18,12 @@ BIO_ssl_shutdown - SSL BIO 


 const BIO_METHOD *BIO_f_ssl(void);



 #define BIO_set_ssl(b,ssl,c)   BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)

 #define BIO_get_ssl(b,sslp)    BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)

 #define BIO_set_ssl_mode(b,client)     BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)

 #define BIO_set_ssl_renegotiate_bytes(b,num) \

        BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);

 #define BIO_set_ssl_renegotiate_timeout(b,seconds) \

        BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);

 #define BIO_get_num_renegotiates(b) \

        BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);

 long BIO_set_ssl(BIO *b,SSL *ssl, long c);

 long BIO_get_ssl(BIO *b, SSL **sslp);

 long BIO_set_ssl_mode(BIO *b, long client);

 long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);

 long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);

 long BIO_get_num_renegotiates(BIO *b);



 BIO *BIO_new_ssl(SSL_CTX *ctx, int client);

 BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
@@ -34,7 +31,7 @@ BIO_ssl_shutdown - SSL BIO 
 int BIO_ssl_copy_session_id(BIO *to, BIO *from);

 void BIO_ssl_shutdown(BIO *bio);



 #define BIO_do_handshake(b)    BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)

 long BIO_do_handshake(BIO *b);



=head1 DESCRIPTION
@@ -128,6 +125,10 @@ Applications do not have to call BIO_do_handshake() but may wish 
to do so to separate the handshake process from other I/O

processing.



BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),

BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),

BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.



=head1 EXAMPLE



This SSL/TLS client example, attempts to retrieve a page from an

doc/crypto/BIO_find_type.pod

+8 −37
Original line number Diff line number Diff line
@@ -2,12 +2,6 @@ 


=head1 NAME



BIO_TYPE_NONE, BIO_TYPE_MEM, BIO_TYPE_FILE, BIO_TYPE_FD, BIO_TYPE_SOCKET,

BIO_TYPE_NULL, BIO_TYPE_SSL, BIO_TYPE_MD, BIO_TYPE_BUFFER, BIO_TYPE_CIPHER,

BIO_TYPE_BASE64, BIO_TYPE_CONNECT, BIO_TYPE_ACCEPT, BIO_TYPE_PROXY_CLIENT,

BIO_TYPE_PROXY_SERVER, BIO_TYPE_NBIO_TEST, BIO_TYPE_NULL_FILTER,

BIO_TYPE_BER, BIO_TYPE_BIO, BIO_TYPE_DESCRIPTOR, BIO_TYPE_FILTER,

BIO_TYPE_SOURCE_SINK,

BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal



=head1 SYNOPSIS
@@ -16,44 +10,21 @@ BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal 


 BIO *BIO_find_type(BIO *b,int bio_type);

 BIO *BIO_next(BIO *b);



 #define BIO_method_type(b)             ((b)->method->type)



 #define BIO_TYPE_NONE          0

 #define BIO_TYPE_MEM           (1|0x0400)

 #define BIO_TYPE_FILE          (2|0x0400)



 #define BIO_TYPE_FD            (4|0x0400|0x0100)

 #define BIO_TYPE_SOCKET                (5|0x0400|0x0100)

 #define BIO_TYPE_NULL          (6|0x0400)

 #define BIO_TYPE_SSL           (7|0x0200)

 #define BIO_TYPE_MD            (8|0x0200)

 #define BIO_TYPE_BUFFER                (9|0x0200)

 #define BIO_TYPE_CIPHER                (10|0x0200)

 #define BIO_TYPE_BASE64                (11|0x0200)

 #define BIO_TYPE_CONNECT       (12|0x0400|0x0100)

 #define BIO_TYPE_ACCEPT                (13|0x0400|0x0100)

 #define BIO_TYPE_PROXY_CLIENT  (14|0x0200)

 #define BIO_TYPE_PROXY_SERVER  (15|0x0200)

 #define BIO_TYPE_NBIO_TEST     (16|0x0200)

 #define BIO_TYPE_NULL_FILTER   (17|0x0200)

 #define BIO_TYPE_BER           (18|0x0200)

 #define BIO_TYPE_BIO           (19|0x0400)



 #define BIO_TYPE_DESCRIPTOR    0x0100

 #define BIO_TYPE_FILTER                0x0200

 #define BIO_TYPE_SOURCE_SINK   0x0400

 int BIO_method_type(const BIO *b);



=head1 DESCRIPTION



The BIO_find_type() searches for a BIO of a given type in a chain, starting

at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search

at BIO B<b>. If B<type> is a specific type (such as B<BIO_TYPE_MEM>) then a search

is made for a BIO of that type. If B<type> is a general type (such as

B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is

searched for. BIO_find_type() returns the next matching BIO or NULL if none is

found.



Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations.

The following general types are defined:

B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>.



For a list of the defined types, see the B<openssl/bio.h> header file.



BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs

in a chain or used in conjunction with BIO_find_type() to find all BIOs of a