X-Git-Url: https://git.openssl.org/gitweb/?a=blobdiff_plain;f=doc%2Fman3%2FSSL_write.pod;h=04cc46b27a5c3b7ec5f0bb8e1262de867d87f0f5;hb=8c47e55ee69500e31e80458682c6e022294cd0be;hp=c860ed7978188d3d747bb40dbf133c16618fe5ba;hpb=ed9fa2c74bbb9da312aa82865aeb3f9b75a8167b;p=openssl.git diff --git a/doc/man3/SSL_write.pod b/doc/man3/SSL_write.pod index c860ed7978..04cc46b27a 100644 --- a/doc/man3/SSL_write.pod +++ b/doc/man3/SSL_write.pod @@ -2,12 +2,13 @@ =head1 NAME -SSL_write_ex, SSL_write - write bytes to a TLS/SSL connection +SSL_write_ex, SSL_write, SSL_sendfile - write bytes to a TLS/SSL connection =head1 SYNOPSIS #include + ossl_ssize_t SSL_sendfile(SSL *s, int fd, off_t offset, size_t size, int flags); int SSL_write_ex(SSL *s, const void *buf, size_t num, size_t *written); int SSL_write(SSL *ssl, const void *buf, int num); @@ -17,6 +18,14 @@ SSL_write_ex() and SSL_write() write B bytes from the buffer B into the specified B connection. On success SSL_write_ex() will store the number of bytes written in B<*written>. +SSL_sendfile() writes B bytes from offset B in the file +descriptor B to the specified SSL connection B. This function provides +efficient zero-copy semantics. SSL_sendfile() is available only when +Kernel TLS is enabled, which can be checked by calling BIO_get_ktls_send(). +It is provided here to allow users to maintain the same interface. +The meaning of B is platform dependent. +Currently, under Linux it is ignored. + =head1 NOTES In the paragraphs below a "write function" is defined as one of either @@ -25,7 +34,7 @@ SSL_write_ex(), or SSL_write(). If necessary, a write function will negotiate a TLS/SSL session, if not already explicitly performed by L or L. If the peer requests a re-negotiation, it will be performed transparently during -the write functio operation. The behaviour of the write functions depends on the +the write function operation. The behaviour of the write functions depends on the underlying BIO. For the transparent negotiation to succeed, the B must have been @@ -34,10 +43,7 @@ L or SSL_set_accept_state() before the first call to a write function. If the underlying BIO is B, the write functions will only return, once -the write operation has been finished or an error occurred, except when a -renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. -This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the -L call. +the write operation has been finished or an error occurred. If the underlying BIO is B the write functions will also return when the underlying BIO could not satisfy the needs of the function to continue @@ -65,9 +71,13 @@ write is performed with the size of a message block, which is 16kB. When a write function call has to be repeated because L returned B or B, it must be repeated with the same arguments. +The data that was passed might have been partially processed. +When B was set using L +the pointer can be different, but the data and length should still be the same. -When calling the write functions with num=0 bytes to be sent the behaviour is -undefined. +You should not call SSL_write() with num=0, it will return an error. +SSL_write_ex() can be called with num=0, but will not send application data to +the peer. =head1 RETURN VALUES @@ -86,23 +96,37 @@ For SSL_write() the following return values can occur: =over 4 -=item E0 +=item E 0 The write operation was successful, the return value is the number of bytes actually written to the TLS/SSL connection. -=item Z<>0 +=item Z<><= 0 + +The write operation was not successful, because either the connection was +closed, an error occurred or action must be taken by the calling process. +Call SSL_get_error() with the return value B to find out the reason. + +Old documentation indicated a difference between 0 and -1, and that -1 was +retryable. +You should instead call SSL_get_error() to find out if it's retryable. -The write operation was not successful. Probably the underlying connection -was closed. Call SSL_get_error() with the return value B to find out, -whether an error occurred or the connection was shut down cleanly -(SSL_ERROR_ZERO_RETURN). +=back + +For SSL_sendfile(), the following return values can occur: -=item E0 +=over 4 -The write operation was not successful, because either an error occurred -or action must be taken by the calling process. Call SSL_get_error() with the -return value B to find out the reason. +=item Z<>>= 0 + +The write operation was successful, the return value is the number +of bytes of the file written to the TLS/SSL connection. + +=item E 0 + +The write operation was not successful, because either the connection was +closed, an error occurred or action must be taken by the calling process. +Call SSL_get_error() with the return value to find out the reason. =back @@ -111,14 +135,19 @@ return value B to find out the reason. L, L, L L, L, L, L -L, -L, L +L, L, +L, L + +=head1 HISTORY + +The SSL_write_ex() function was added in OpenSSL 1.1.1. +The SSL_sendfile() function was added in OpenSSL 3.0. =head1 COPYRIGHT -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. -Licensed under the OpenSSL license (the "License"). You may not use +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 L.