secure/lib/libcrypto/man/SSL_get_all_async_fds.3

   1 .\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_GET_ALL_ASYNC_FDS 3"
 136 .TH SSL_GET_ALL_ASYNC_FDS 3 "2019-02-26" "1.1.1b" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_waiting_for_async, SSL_get_all_async_fds, SSL_get_changed_async_fds \&\- manage asynchronous operations
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 2
 146 \& #include <openssl/async.h>
 147 \& #include <openssl/ssl.h>
 148 \&
 149 \& int SSL_waiting_for_async(SSL *s);
 150 \& int SSL_get_all_async_fds(SSL *s, OSSL_ASYNC_FD *fd, size_t *numfds);
 151 \& int SSL_get_changed_async_fds(SSL *s, OSSL_ASYNC_FD *addfd, size_t *numaddfds,
 152 \&                               OSSL_ASYNC_FD *delfd, size_t *numdelfds);
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 \&\fBSSL_waiting_for_async()\fR determines whether an \s-1SSL\s0 connection is currently
 157 waiting for asynchronous operations to complete (see the \s-1SSL_MODE_ASYNC\s0 mode in
 158 \&\fBSSL_CTX_set_mode\fR\|(3)).
 159 .PP
 160 \&\fBSSL_get_all_async_fds()\fR returns a list of file descriptor which can be used in a
 161 call to \fBselect()\fR or \fBpoll()\fR to determine whether the current asynchronous
 162 operation has completed or not. A completed operation will result in data
 163 appearing as \*(L"read ready\*(R" on the file descriptor (no actual data should be read
 164 from the file descriptor). This function should only be called if the \s-1SSL\s0 object
 165 is currently waiting for asynchronous work to complete (i.e.
 166 \&\s-1SSL_ERROR_WANT_ASYNC\s0 has been received \- see \fBSSL_get_error\fR\|(3)). Typically the
 167 list will only contain one file descriptor. However if multiple asynchronous
 168 capable engines are in use then more than one is possible. The number of file
 169 descriptors returned is stored in \fB*numfds\fR and the file descriptors themselves
 170 are in \fB*fds\fR. The \fBfds\fR parameter may be \s-1NULL\s0 in which case no file
 171 descriptors are returned but \fB*numfds\fR is still populated. It is the callers
 172 responsibility to ensure sufficient memory is allocated at \fB*fds\fR so typically
 173 this function is called twice (once with a \s-1NULL\s0 \fBfds\fR parameter and once
 174 without).
 175 .PP
 176 \&\fBSSL_get_changed_async_fds()\fR returns a list of the asynchronous file descriptors
 177 that have been added and a list that have been deleted since the last
 178 \&\s-1SSL_ERROR_WANT_ASYNC\s0 was received (or since the \s-1SSL\s0 object was created if no
 179 \&\s-1SSL_ERROR_WANT_ASYNC\s0 has been received). Similar to \fBSSL_get_all_async_fds()\fR it
 180 is the callers responsibility to ensure that \fB*addfd\fR and \fB*delfd\fR have
 181 sufficient memory allocated, although they may be \s-1NULL.\s0 The number of added fds
 182 and the number of deleted fds are stored in \fB*numaddfds\fR and \fB*numdelfds\fR
 183 respectively.
 184 .SH "RETURN VALUES"
 185 .IX Header "RETURN VALUES"
 186 \&\fBSSL_waiting_for_async()\fR will return 1 if the current \s-1SSL\s0 operation is waiting
 187 for an async operation to complete and 0 otherwise.
 188 .PP
 189 \&\fBSSL_get_all_async_fds()\fR and \fBSSL_get_changed_async_fds()\fR return 1 on success or
 190 0 on error.
 191 .SH "NOTES"
 192 .IX Header "NOTES"
 193 On Windows platforms the openssl/async.h header is dependent on some
 194 of the types customarily made available by including windows.h. The
 195 application developer is likely to require control over when the latter
 196 is included, commonly as one of the first included headers. Therefore
 197 it is defined as an application developer's responsibility to include
 198 windows.h prior to async.h.
 199 .SH "SEE ALSO"
 200 .IX Header "SEE ALSO"
 201 \&\fBSSL_get_error\fR\|(3), \fBSSL_CTX_set_mode\fR\|(3)
 202 .SH "HISTORY"
 203 .IX Header "HISTORY"
 204 The \fBSSL_waiting_for_async()\fR, \fBSSL_get_all_async_fds()\fR
 205 and \fBSSL_get_changed_async_fds()\fR functions were added in OpenSSL 1.1.0.
 206 .SH "COPYRIGHT"
 207 .IX Header "COPYRIGHT"
 208 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
 209 .PP
 210 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 211 this file except in compliance with the License.  You can obtain a copy
 212 in the file \s-1LICENSE\s0 in the source distribution or at
 213 <https://www.openssl.org/source/license.html>.