diff options
Diffstat (limited to 'static/freebsd/man3/BIO_meth_new.3')
| -rw-r--r-- | static/freebsd/man3/BIO_meth_new.3 | 277 |
1 files changed, 277 insertions, 0 deletions
diff --git a/static/freebsd/man3/BIO_meth_new.3 b/static/freebsd/man3/BIO_meth_new.3 new file mode 100644 index 00000000..ffa66e88 --- /dev/null +++ b/static/freebsd/man3/BIO_meth_new.3 @@ -0,0 +1,277 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Required to disable full justification in groff 1.23.0. +.if n .ds AD l +.\" ======================================================================== +.\" +.IX Title "BIO_METH_NEW 3ossl" +.TH BIO_METH_NEW 3ossl 2026-04-07 3.5.6 OpenSSL +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +BIO_get_new_index, +BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex, +BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write, +BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, +BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, +BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create, +BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl, +BIO_meth_set_callback_ctrl, BIO_meth_set_sendmmsg, BIO_meth_get_sendmmsg, +BIO_meth_set_recvmmsg, BIO_meth_get_recvmmsg \- Routines to build up BIO methods +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& #include <openssl/bio.h> +\& +\& int BIO_get_new_index(void); +\& +\& BIO_METHOD *BIO_meth_new(int type, const char *name); +\& +\& void BIO_meth_free(BIO_METHOD *biom); +\& +\& int BIO_meth_set_write_ex(BIO_METHOD *biom, +\& int (*bwrite)(BIO *, const char *, size_t, size_t *)); +\& int BIO_meth_set_write(BIO_METHOD *biom, +\& int (*write)(BIO *, const char *, int)); +\& +\& int BIO_meth_set_read_ex(BIO_METHOD *biom, +\& int (*bread)(BIO *, char *, size_t, size_t *)); +\& int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int)); +\& +\& int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *)); +\& int BIO_meth_set_gets(BIO_METHOD *biom, +\& int (*gets)(BIO *, char *, int)); +\& +\& int BIO_meth_set_ctrl(BIO_METHOD *biom, +\& long (*ctrl)(BIO *, int, long, void *)); +\& +\& int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *)); +\& int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *)); +\& +\& int BIO_meth_set_callback_ctrl(BIO_METHOD *biom, +\& long (*callback_ctrl)(BIO *, int, BIO_info_cb *)); +\& +\& int BIO_meth_set_sendmmsg(BIO_METHOD *biom, +\& ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t, +\& size_t, uint64_t)); +\& int BIO_meth_set_recvmmsg(BIO_METHOD *biom, +\& ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t, +\& size_t, uint64_t)); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.5: +.PP +.Vb 3 +\& int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t, +\& size_t *); +\& int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int); +\& +\& int (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *); +\& int (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int); +\& +\& int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *); +\& int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int); +\& +\& long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *); +\& +\& int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *); +\& int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *); +\& +\& long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *); +\& +\& ossl_ssize_t (*BIO_meth_get_sendmmsg(const BIO_METHOD *biom))(BIO *, +\& BIO_MSG *, +\& size_t, +\& size_t, +\& uint64_t); +\& ossl_ssize_t (*BIO_meth_get_recvmmsg(const BIO_METHOD *biom))(BIO *, +\& BIO_MSG *, +\& size_t, +\& size_t, +\& uint64_t); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBBIO_METHOD\fR type is a structure used for the implementation of new BIO +types. It provides a set of functions used by OpenSSL for the implementation +of the various BIO capabilities. See the \fBbio\fR\|(7) page for more information. +.PP +\&\fBBIO_meth_new()\fR creates a new \fBBIO_METHOD\fR structure that contains a type +identifier \fItype\fR and a string that represents its \fBname\fR. +\&\fBtype\fR can be set to either \fBBIO_TYPE_NONE\fR or via \fBBIO_get_new_index()\fR if +a unique type is required for searching (See \fBBIO_find_type\fR\|(3)) +.PP +Note that \fBBIO_get_new_index()\fR can only be used 127 times before it returns an +error. +.PP +The set of +standard OpenSSL provided BIO types is provided in \fI<openssl/bio.h>\fR. +Some examples include \fBBIO_TYPE_BUFFER\fR and \fBBIO_TYPE_CIPHER\fR. Filter BIOs +should have a type which have the "filter" bit set (\fBBIO_TYPE_FILTER\fR). +Source/sink BIOs should have the "source/sink" bit set (\fBBIO_TYPE_SOURCE_SINK\fR). +File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should +additionally have the "descriptor" bit set (\fBBIO_TYPE_DESCRIPTOR\fR). See the +\&\fBBIO_find_type\fR\|(3) page for more information. +.PP +\&\fBBIO_meth_free()\fR destroys a \fBBIO_METHOD\fR structure and frees up any memory +associated with it. If the argument is NULL, nothing is done. +.PP +\&\fBBIO_meth_get_write_ex()\fR and \fBBIO_meth_set_write_ex()\fR get and set the function +used for writing arbitrary length data to the BIO respectively. This function +will be called in response to the application calling \fBBIO_write_ex()\fR or +\&\fBBIO_write()\fR. The parameters for the function have the same meaning as for +\&\fBBIO_write_ex()\fR. Older code may call \fBBIO_meth_get_write()\fR and +\&\fBBIO_meth_set_write()\fR instead. Applications should not call both +\&\fBBIO_meth_set_write_ex()\fR and \fBBIO_meth_set_write()\fR or call \fBBIO_meth_get_write()\fR +when the function was set with \fBBIO_meth_set_write_ex()\fR. +.PP +\&\fBBIO_meth_get_read_ex()\fR and \fBBIO_meth_set_read_ex()\fR get and set the function used +for reading arbitrary length data from the BIO respectively. This function will +be called in response to the application calling \fBBIO_read_ex()\fR or \fBBIO_read()\fR. +The parameters for the function have the same meaning as for \fBBIO_read_ex()\fR. +Older code may call \fBBIO_meth_get_read()\fR and \fBBIO_meth_set_read()\fR instead. +Applications should not call both \fBBIO_meth_set_read_ex()\fR and \fBBIO_meth_set_read()\fR +or call \fBBIO_meth_get_read()\fR when the function was set with +\&\fBBIO_meth_set_read_ex()\fR. +.PP +\&\fBBIO_meth_get_puts()\fR and \fBBIO_meth_set_puts()\fR get and set the function used for +writing a NULL terminated string to the BIO respectively. This function will be +called in response to the application calling \fBBIO_puts()\fR. The parameters for +the function have the same meaning as for \fBBIO_puts()\fR. +.PP +\&\fBBIO_meth_get_gets()\fR and \fBBIO_meth_set_gets()\fR get and set the function typically +used for reading a line of data from the BIO respectively (see the \fBBIO_gets\fR\|(3) +page for more information). This function will be called in response to the +application calling \fBBIO_gets()\fR. The parameters for the function have the same +meaning as for \fBBIO_gets()\fR. +.PP +\&\fBBIO_meth_get_ctrl()\fR and \fBBIO_meth_set_ctrl()\fR get and set the function used for +processing ctrl messages in the BIO respectively. See the \fBBIO_ctrl\fR\|(3) page for +more information. This function will be called in response to the application +calling \fBBIO_ctrl()\fR. The parameters for the function have the same meaning as for +\&\fBBIO_ctrl()\fR. +.PP +\&\fBBIO_meth_get_create()\fR and \fBBIO_meth_set_create()\fR get and set the function used +for creating a new instance of the BIO respectively. This function will be +called in response to the application calling \fBBIO_new()\fR and passing +in a pointer to the current BIO_METHOD. The \fBBIO_new()\fR function will allocate the +memory for the new BIO, and a pointer to this newly allocated structure will +be passed as a parameter to the function. If a create function is set, +\&\fBBIO_new()\fR will not mark the BIO as initialised on allocation. +\&\fBBIO_set_init\fR\|(3) must then be called either by the create function, or later, +by a BIO ctrl function, once BIO initialisation is complete. +.PP +\&\fBBIO_meth_get_destroy()\fR and \fBBIO_meth_set_destroy()\fR get and set the function used +for destroying an instance of a BIO respectively. This function will be +called in response to the application calling \fBBIO_free()\fR. A pointer to the BIO +to be destroyed is passed as a parameter. The destroy function should be used +for BIO specific clean up. The memory for the BIO itself should not be freed by +this function. +.PP +\&\fBBIO_meth_get_callback_ctrl()\fR and \fBBIO_meth_set_callback_ctrl()\fR get and set the +function used for processing callback ctrl messages in the BIO respectively. See +the \fBBIO_callback_ctrl\fR\|(3) page for more information. This function will be called +in response to the application calling \fBBIO_callback_ctrl()\fR. The parameters for +the function have the same meaning as for \fBBIO_callback_ctrl()\fR. +.PP +\&\fBBIO_meth_get_sendmmsg()\fR, \fBBIO_meth_set_sendmmsg()\fR, \fBBIO_meth_get_recvmmsg()\fR and +\&\fBBIO_meth_set_recvmmsg()\fR get and set the functions used for handling +\&\fBBIO_sendmmsg()\fR and \fBBIO_recvmmsg()\fR calls respectively. See \fBBIO_sendmmsg\fR\|(3) for +more information. +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fBBIO_get_new_index()\fR returns the new BIO type value or \-1 if an error occurred. +.PP +BIO_meth_new(int type, const char *name) returns a valid \fBBIO_METHOD\fR or NULL +if an error occurred. +.PP +The \fBBIO_meth_set\fR functions return 1 on success or 0 on error. +.PP +The \fBBIO_meth_get\fR functions return the corresponding function pointers. +.SH BUGS +.IX Header "BUGS" +It is not safe to use \f(CW\*(C`BIO_meth_get_\*(C'\fR functions to reuse the \fBBIO\fR +implementation of \fBBIO\fRs implemented by OpenSSL itself with +application\-implemented \fBBIO\fRs. Instead either the applications ought to +implement these functions themselves or they should implement a filter BIO. +.PP +For more details please see <https://github.com/openssl/openssl/issues/26047>. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBbio\fR\|(7), \fBBIO_find_type\fR\|(3), \fBBIO_ctrl\fR\|(3), \fBBIO_read_ex\fR\|(3), \fBBIO_new\fR\|(3) +.SH HISTORY +.IX Header "HISTORY" +The functions \fBBIO_meth_get_sendmmsg()\fR, \fBBIO_meth_set_sendmmsg()\fR, +\&\fBBIO_meth_get_recvmmsg()\fR and \fBBIO_meth_set_recvmmsg()\fR were added in OpenSSL 3.2. +.PP +All the other functions described here were added in OpenSSL 1.1.0. +.PP +The functions \fBBIO_meth_get_read_ex()\fR, \fBBIO_meth_get_write_ex()\fR, +\&\fBBIO_meth_get_write()\fR, \fBBIO_meth_get_read()\fR, \fBBIO_meth_get_puts()\fR, +\&\fBBIO_meth_get_gets()\fR, \fBBIO_meth_get_ctrl()\fR, \fBBIO_meth_get_create()\fR, +\&\fBBIO_meth_get_destroy()\fR, \fBBIO_meth_get_callback_ctrl()\fR, +\&\fBBIO_meth_get_sendmmsg()\fR and \fBBIO_meth_get_recvmmsg()\fR are deprecated since +OpenSSL 3.5. +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the Apache License 2.0 (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 +<https://www.openssl.org/source/license.html>. |