BIO control function introduction
--- Translation according to OpenSSL DOC / CRYPTO / BIO / BIO_CTRL.POD and its own understanding
(Author: DragonKing Mail: wzhah@263.net Posted on:
Http://gdwzh.126.com OpenSSL Professional Forum)
There are many BIO control functions, and different BIO types have different control functions. Here is simply introduced some universal BIO control functions, as for some type of BIO's specific control function, refer to subsequent files.
The general control function of BIO has the following, which is as follows (openssl / bio.h):
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);
Char * bio_ptr_ctrl (BIO * BP, INT CMD, Long Lar);
Long Bio_INT_CTRL (BIO * BP, INT CMD, Long Larg, Int IARG);
INT BIO_RESET (BIO * B);
INT BIO_SEEK (BIO * B, INT OFS);
INT BIO_TELL (BIO * B);
INT BIO_FLUSH (BIO * B);
INT BIO_EOF (BIO * B);
INT BIO_SET_CLOSE (BIO * B, Long Flag);
INT BIO_GET_CLOSE (BIO * B);
INT BIO_PENDING (BIO * B);
INT BIO_WPENDING (BIO * B);
SIZE_T BIO_CTRL_PENDING (BIO * B);
SIZE_T BIO_CTRL_WPENDING (BIO * B);
In fact, in these functions, in addition to BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_ctrl_pending, BIO_ctrl_wpending outer real function, the other is a macro definition, and, in these functions, in addition to BIO_ctrl, BIO_callback_ctrl, other basically simple BIO_CTRL inputs different parameters calls. Let's introduce these functions.
[BIO_CTRL]
From the above description, BIO_CTRL is the most basic function in the entire control function, which supports different command inputs, thereby producing different functions, thereby derived many other functions, as a control function of a comparison formation Generally speaking, the user does not need to call it directly, because many functions that have been directly facing users have been built directly on it.
Filter type BIO does not define a Bio_ctrl feature. If you call this function, they simply pass the command to the next Bio in the BIO chain. That is, it is usually possible to call a BIO_ctrl function directly to call only, only the function is called on its BIO chain, then the BIO chain will automatically pass the call function to the corresponding BIO. This may result in some unexpected results, for example, the BIO_SEEK () function is not implemented in the current Filter type BIO (everyone will understand Bio_Seek is the simple macro definition of Bio_ctrl), but if it is in this Bio chain The end is a file or file descriptor Bio, then this call will return successful results.
For Source / Sink type BIO, if they don't recognize the operation defined by bio_ctrl, then it returns 0. [BIO_CALLBACK_CTRL]
This function is the only one in this set of controls is not built by calling Bio_Ctrl, it has its own implementation function, and it is not coherent to Bio_Ctrl. Like Bio_Ctrl, it is also a comparative underlying control function, which defines some of the control functions directly facing the user above. In general, the user does not need to call the function directly.
It should be noted that the function and the BIO_CTRL function have different BIO_CTRL control functions in order to implement different types of BIOs, and their operations are basically defined by the Callback functions of each BIO. This is the foundation of different BIOs to achieve different functions.
[BIO_PTR_CTRL and BIO_INT_CTRL]
Both functions are simple to call the Bio_ctrl function. Different, the latter is input to the four parameters and passed into the BIO_CTRL function, simply returns the return value returned by calling BIO_CTRL; and the former only entered three Parameters, the last BIO_CTRL parameter is an output parameter and is used as a return value.
[BIO_RESET]
This function is a macro definition function of Bio_ctrl. In order to have a sense of sensibility for the macro definition function of Bio_Ctrl, I wrote this macro definition, as follows:
#define bio_reset (b) (int) BIO_CTRL (B, Bio_Ctrl_Reset, 0, NULL)
This is the typical macro definition of Bio_Ctrl, which produces a large number of control functions in this way. As the name suggests, the BIO_RESET function is simply simple to set the BIO's status to the initialization, such as file BIO, calling this function to point the file pointer to the file start position.
In general, the function returns 1 when calling success, returns 0 or -1 at the time of failure; but the file BIO is an exception. When the success is called, it returns to 0, returns -1 when it fails.
[BIO_SEEK]
This function is also a macro definition function of BIO_CTRL, which is defined as follows:
#define Bio_seek (B, OFS) (int) BIO_CTRL (B, BIO_C_FILE_SEEK, OFS, NULL)
This function knows the file pointer of the file-related BIO (file and file descriptor type) to the position of the starting position OFS (input parameter) byte. When the call is successful, return the position pointer of the file, otherwise returns -1; but the file BIO exception, return 0 when successful, return -1 when it fails.
[BIO_TELL]
This function is also a macro definition function of BIO_CTRL, which is defined as follows:
#define bio_tell (b) (int) BIO_CTRL (B, BIO_C_FILE_TELL, 0, NULL)
This function returns the current file pointer position of the file-related BIO. Like Bio_Seek, when the call is successful, return the location pointer of the file, otherwise returns -1; but the file BIO exception, return 0 when successful, return -1 when it fails.
[BIO_FLUSH]
This function is also a macro definition function of BIO_CTRL, which is defined as follows:
#define bio_flush (b) (int) BIO_CTRL (B, Bio_ctrl_flush, 0, null)
This function is used to write the data of the BIO internal buffer, some, and it is also used to write in order to view in accordance with EOF. When the call is successful, the function returns 1 and returns 0 or -1 when it fails. Returns 0 or -1 when it fails, is to mark this operation to try again in the same way as Bio_Write (). At this time, the BIO_SHOULD_RETRY () function should be called. Of course, the call to the function should be failed if normal. [BIO_EOF]
This function is also a macro definition function of BIO_CTRL, which is defined as follows.
#define bio_eof (b) (int) BIO_CTRL (B, Bio_ctrl_eof, 0, null)
If the BIO is read, the function returns 1, as for the specific definition of EOF, according to the type of the BIO. If you do not read EOF, the function returns 0.
[BIO_SET_CLOSE]
This function is also a macro definition function of BIO_CTRL, which is defined as follows:
#define bio_set_close (b, c) (int) BIO_CTRL (B, Bio_Ctrl_set_close, (c), null)
This function sets the shutdown flag of the BIO, which can be BIO_CLOSE or BIO_NOCLOSE. In general, the flag is to indicate whether the I / O stream is turned off when the Bio is released at the Source / Sink type BIO. This function always returns 1.
[BIO_GET_CLOSE]
This function is also a macro definition function of BIO_CTRL, which is defined as follows:
#define bio_get_close (b) (int) BIO_CTRL (B, Bio_Ctrl_get_close, 0, null)
This function reads the shutdown flag of the BIO, returns BIO_CLOSE or BIO_NOCLOSE.
[BIO_PENDING, BIO_WPENDING, BIO_CTRL_PENDING and BIO_CTRL_WPENDING]
These functions are used to obtain the number of characters in the BIO read cache or write cache, return the number of characters in the corresponding cache.
The front two functions are also a macro definition function of BIO_CTRL, which is defined as follows:
#define bio_pending (b) (int) BIO_CTRL (B, Bio_Ctrl_pending, 0, null)
#define bio_wpending (b) (int) BIO_CTRL (B, Bio_ctrl_wpending, 0, null)
The latter two function functions are the same as they, but they are implemented by calling the BIO_CTRL function instead of macro definition. In addition, the front two functions returns the INT type, and the two functions returned by the two functions are Size_T.
It should be noted that bio_pending and bio_wpending are not the number of cache data very reliably in all cases. For example, in the file BIO, some data may be valid in the cache of the file internal structure, but it is impossible to simple. The number of these data is obtained in the BIO. And in some types of BIO, these two functions may not be supported. Based on this, the OpenSSL author itself recommends that these two functions are generally not used, but use two behind unless you do what you do is very clear and understand.
