BIO_meth_new.pod 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164
  1. =pod
  2. =head1 NAME
  3. BIO_get_new_index,
  4. BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex,
  5. BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write,
  6. BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts,
  7. BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl,
  8. BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create,
  9. BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
  10. BIO_meth_set_callback_ctrl - Routines to build up BIO methods
  11. =head1 SYNOPSIS
  12. #include <openssl/bio.h>
  13. int BIO_get_new_index(void);
  14. BIO_METHOD *BIO_meth_new(int type, const char *name);
  15. void BIO_meth_free(BIO_METHOD *biom);
  16. int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t,
  17. size_t *);
  18. int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int);
  19. int BIO_meth_set_write_ex(BIO_METHOD *biom,
  20. int (*bwrite)(BIO *, const char *, size_t, size_t *));
  21. int BIO_meth_set_write(BIO_METHOD *biom,
  22. int (*write)(BIO *, const char *, int));
  23. int (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *);
  24. int (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int);
  25. int BIO_meth_set_read_ex(BIO_METHOD *biom,
  26. int (*bread)(BIO *, char *, size_t, size_t *));
  27. int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int));
  28. int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *);
  29. int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *));
  30. int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int);
  31. int BIO_meth_set_gets(BIO_METHOD *biom,
  32. int (*gets)(BIO *, char *, int));
  33. long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *);
  34. int BIO_meth_set_ctrl(BIO_METHOD *biom,
  35. long (*ctrl)(BIO *, int, long, void *));
  36. int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *);
  37. int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *));
  38. int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *);
  39. int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *));
  40. long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *);
  41. int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
  42. long (*callback_ctrl)(BIO *, int, BIO_info_cb *));
  43. =head1 DESCRIPTION
  44. The B<BIO_METHOD> type is a structure used for the implementation of new BIO
  45. types. It provides a set of functions used by OpenSSL for the implementation
  46. of the various BIO capabilities. See the L<bio(7)> page for more information.
  47. BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a
  48. unique integer B<type> and a string that represents its B<name>.
  49. Use BIO_get_new_index() to get the value for B<type>.
  50. The set of
  51. standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples
  52. include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a
  53. type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs
  54. should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor
  55. based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
  56. "descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type(3)> page for
  57. more information.
  58. BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
  59. associated with it.
  60. BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function
  61. used for writing arbitrary length data to the BIO respectively. This function
  62. will be called in response to the application calling BIO_write_ex() or
  63. BIO_write(). The parameters for the function have the same meaning as for
  64. BIO_write_ex(). Older code may call BIO_meth_get_write() and
  65. BIO_meth_set_write() instead. Applications should not call both
  66. BIO_meth_set_write_ex() and BIO_meth_set_write() or call BIO_meth_get_write()
  67. when the function was set with BIO_meth_set_write_ex().
  68. BIO_meth_get_read_ex() and BIO_meth_set_read_ex() get and set the function used
  69. for reading arbitrary length data from the BIO respectively. This function will
  70. be called in response to the application calling BIO_read_ex() or BIO_read().
  71. The parameters for the function have the same meaning as for BIO_read_ex().
  72. Older code may call BIO_meth_get_read() and BIO_meth_set_read() instead.
  73. Applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read()
  74. or call BIO_meth_get_read() when the function was set with
  75. BIO_meth_set_read_ex().
  76. BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
  77. writing a NULL terminated string to the BIO respectively. This function will be
  78. called in response to the application calling BIO_puts(). The parameters for
  79. the function have the same meaning as for BIO_puts().
  80. BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
  81. used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)>
  82. page for more information). This function will be called in response to the
  83. application calling BIO_gets(). The parameters for the function have the same
  84. meaning as for BIO_gets().
  85. BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
  86. processing ctrl messages in the BIO respectively. See the L<BIO_ctrl(3)> page for
  87. more information. This function will be called in response to the application
  88. calling BIO_ctrl(). The parameters for the function have the same meaning as for
  89. BIO_ctrl().
  90. BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
  91. for creating a new instance of the BIO respectively. This function will be
  92. called in response to the application calling BIO_new() and passing
  93. in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
  94. memory for the new BIO, and a pointer to this newly allocated structure will
  95. be passed as a parameter to the function.
  96. BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
  97. for destroying an instance of a BIO respectively. This function will be
  98. called in response to the application calling BIO_free(). A pointer to the BIO
  99. to be destroyed is passed as a parameter. The destroy function should be used
  100. for BIO specific clean up. The memory for the BIO itself should not be freed by
  101. this function.
  102. BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
  103. function used for processing callback ctrl messages in the BIO respectively. See
  104. the L<BIO_callback_ctrl(3)> page for more information. This function will be called
  105. in response to the application calling BIO_callback_ctrl(). The parameters for
  106. the function have the same meaning as for BIO_callback_ctrl().
  107. =head1 RETURN VALUES
  108. BIO_get_new_index() returns the new BIO type value or -1 if an error occurred.
  109. BIO_meth_new(int type, const char *name) returns a valid B<BIO_METHOD> or NULL
  110. if an error occurred.
  111. The B<BIO_meth_set> functions return 1 on success or 0 on error.
  112. The B<BIO_meth_get> functions return the corresponding function pointers.
  113. =head1 SEE ALSO
  114. L<bio(7)>, L<BIO_find_type(3)>, L<BIO_ctrl(3)>, L<BIO_read_ex(3)>, L<BIO_new(3)>
  115. =head1 HISTORY
  116. The functions described here were added in OpenSSL 1.1.0.
  117. =head1 COPYRIGHT
  118. Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
  119. Licensed under the Apache License 2.0 (the "License"). You may not use
  120. this file except in compliance with the License. You can obtain a copy
  121. in the file LICENSE in the source distribution or at
  122. L<https://www.openssl.org/source/license.html>.
  123. =cut