secure/lib/libcrypto/man/man3/ASYNC_WAIT_CTX_new.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   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 "ASYNC_WAIT_CTX_NEW 3"
 136 .TH ASYNC_WAIT_CTX_NEW 3 "2022-05-03" "1.1.1o" "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 ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd \- functions to manage waiting for asynchronous jobs to complete
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/async.h>
 147 \&
 148 \& ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
 149 \& void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
 150 \& int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
 151 \&                                OSSL_ASYNC_FD fd,
 152 \&                                void *custom_data,
 153 \&                                void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
 154 \&                                                OSSL_ASYNC_FD, void *));
 155 \& int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
 156 \&                           OSSL_ASYNC_FD *fd, void **custom_data);
 157 \& int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
 158 \&                                size_t *numfds);
 159 \& int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
 160 \&                                    size_t *numaddfds, OSSL_ASYNC_FD *delfd,
 161 \&                                    size_t *numdelfds);
 162 \& int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
 163 .Ve
 164 .SH "DESCRIPTION"
 165 .IX Header "DESCRIPTION"
 166 For an overview of how asynchronous operations are implemented in OpenSSL see
 167 \&\fBASYNC_start_job\fR\|(3). An \s-1ASYNC_WAIT_CTX\s0 object represents an asynchronous
 168 \&\*(L"session\*(R", i.e. a related set of crypto operations. For example in \s-1SSL\s0 terms
 169 this would have a one-to-one correspondence with an \s-1SSL\s0 connection.
 170 .PP
 171 Application code must create an \s-1ASYNC_WAIT_CTX\s0 using the \fBASYNC_WAIT_CTX_new()\fR
 172 function prior to calling \fBASYNC_start_job()\fR (see \fBASYNC_start_job\fR\|(3)). When
 173 the job is started it is associated with the \s-1ASYNC_WAIT_CTX\s0 for the duration of
 174 that job. An \s-1ASYNC_WAIT_CTX\s0 should only be used for one \s-1ASYNC_JOB\s0 at any one
 175 time, but can be reused after an \s-1ASYNC_JOB\s0 has finished for a subsequent
 176 \&\s-1ASYNC_JOB.\s0 When the session is complete (e.g. the \s-1SSL\s0 connection is closed),
 177 application code cleans up with \fBASYNC_WAIT_CTX_free()\fR.
 178 .PP
 179 ASYNC_WAIT_CTXs can have \*(L"wait\*(R" file descriptors associated with them. Calling
 180 \&\fBASYNC_WAIT_CTX_get_all_fds()\fR and passing in a pointer to an \s-1ASYNC_WAIT_CTX\s0 in
 181 the \fBctx\fR parameter will return the wait file descriptors associated with that
 182 job in \fB*fd\fR. The number of file descriptors returned will be stored in
 183 \&\fB*numfds\fR. It is the caller's responsibility to ensure that sufficient memory
 184 has been allocated in \fB*fd\fR to receive all the file descriptors. Calling
 185 \&\fBASYNC_WAIT_CTX_get_all_fds()\fR with a \s-1NULL\s0 \fBfd\fR value will return no file
 186 descriptors but will still populate \fB*numfds\fR. Therefore, application code is
 187 typically expected to call this function twice: once to get the number of fds,
 188 and then again when sufficient memory has been allocated. If only one
 189 asynchronous engine is being used then normally this call will only ever return
 190 one fd. If multiple asynchronous engines are being used then more could be
 191 returned.
 192 .PP
 193 The function \fBASYNC_WAIT_CTX_get_changed_fds()\fR can be used to detect if any fds
 194 have changed since the last call time \fBASYNC_start_job()\fR returned an \s-1ASYNC_PAUSE\s0
 195 result (or since the \s-1ASYNC_WAIT_CTX\s0 was created if no \s-1ASYNC_PAUSE\s0 result has
 196 been received). The \fBnumaddfds\fR and \fBnumdelfds\fR parameters will be populated
 197 with the number of fds added or deleted respectively. \fB*addfd\fR and \fB*delfd\fR
 198 will be populated with the list of added and deleted fds respectively. Similarly
 199 to \fBASYNC_WAIT_CTX_get_all_fds()\fR either of these can be \s-1NULL,\s0 but if they are not
 200 \&\s-1NULL\s0 then the caller is responsible for ensuring sufficient memory is allocated.
 201 .PP
 202 Implementors of async aware code (e.g. engines) are encouraged to return a
 203 stable fd for the lifetime of the \s-1ASYNC_WAIT_CTX\s0 in order to reduce the \*(L"churn\*(R"
 204 of regularly changing fds \- although no guarantees of this are provided to
 205 applications.
 206 .PP
 207 Applications can wait for the file descriptor to be ready for \*(L"read\*(R" using a
 208 system function call such as select or poll (being ready for \*(L"read\*(R" indicates
 209 that the job should be resumed). If no file descriptor is made available then an
 210 application will have to periodically \*(L"poll\*(R" the job by attempting to restart it
 211 to see if it is ready to continue.
 212 .PP
 213 Async aware code (e.g. engines) can get the current \s-1ASYNC_WAIT_CTX\s0 from the job
 214 via \fBASYNC_get_wait_ctx\fR\|(3) and provide a file descriptor to use for waiting
 215 on by calling \fBASYNC_WAIT_CTX_set_wait_fd()\fR. Typically this would be done by an
 216 engine immediately prior to calling \fBASYNC_pause_job()\fR and not by end user code.
 217 An existing association with a file descriptor can be obtained using
 218 \&\fBASYNC_WAIT_CTX_get_fd()\fR and cleared using \fBASYNC_WAIT_CTX_clear_fd()\fR. Both of
 219 these functions requires a \fBkey\fR value which is unique to the async aware
 220 code.  This could be any unique value but a good candidate might be the
 221 \&\fB\s-1ENGINE\s0 *\fR for the engine. The \fBcustom_data\fR parameter can be any value, and
 222 will be returned in a subsequent call to \fBASYNC_WAIT_CTX_get_fd()\fR. The
 223 \&\fBASYNC_WAIT_CTX_set_wait_fd()\fR function also expects a pointer to a \*(L"cleanup\*(R"
 224 routine. This can be \s-1NULL\s0 but if provided will automatically get called when
 225 the \s-1ASYNC_WAIT_CTX\s0 is freed, and gives the engine the opportunity to close the
 226 fd or any other resources. Note: The \*(L"cleanup\*(R" routine does not get called if
 227 the fd is cleared directly via a call to \fBASYNC_WAIT_CTX_clear_fd()\fR.
 228 .PP
 229 An example of typical usage might be an async capable engine. User code would
 230 initiate cryptographic operations. The engine would initiate those operations
 231 asynchronously and then call \fBASYNC_WAIT_CTX_set_wait_fd()\fR followed by
 232 \&\fBASYNC_pause_job()\fR to return control to the user code. The user code can then
 233 perform other tasks or wait for the job to be ready by calling \*(L"select\*(R" or other
 234 similar function on the wait file descriptor. The engine can signal to the user
 235 code that the job should be resumed by making the wait file descriptor
 236 \&\*(L"readable\*(R". Once resumed the engine should clear the wake signal on the wait
 237 file descriptor.
 238 .SH "RETURN VALUES"
 239 .IX Header "RETURN VALUES"
 240 \&\fBASYNC_WAIT_CTX_new()\fR returns a pointer to the newly allocated \s-1ASYNC_WAIT_CTX\s0 or
 241 \&\s-1NULL\s0 on error.
 242 .PP
 243 ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
 244 ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on
 245 success or 0 on error.
 246 .SH "NOTES"
 247 .IX Header "NOTES"
 248 On Windows platforms the openssl/async.h header is dependent on some
 249 of the types customarily made available by including windows.h. The
 250 application developer is likely to require control over when the latter
 251 is included, commonly as one of the first included headers. Therefore,
 252 it is defined as an application developer's responsibility to include
 253 windows.h prior to async.h.
 254 .SH "SEE ALSO"
 255 .IX Header "SEE ALSO"
 256 \&\fBcrypto\fR\|(7), \fBASYNC_start_job\fR\|(3)
 257 .SH "HISTORY"
 258 .IX Header "HISTORY"
 259 \&\fBASYNC_WAIT_CTX_new()\fR, \fBASYNC_WAIT_CTX_free()\fR, \fBASYNC_WAIT_CTX_set_wait_fd()\fR,
 260 \&\fBASYNC_WAIT_CTX_get_fd()\fR, \fBASYNC_WAIT_CTX_get_all_fds()\fR,
 261 \&\fBASYNC_WAIT_CTX_get_changed_fds()\fR and \fBASYNC_WAIT_CTX_clear_fd()\fR
 262 were added in OpenSSL 1.1.0.
 263 .SH "COPYRIGHT"
 264 .IX Header "COPYRIGHT"
 265 Copyright 2016\-2020 The OpenSSL Project Authors. All Rights Reserved.
 266 .PP
 267 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 268 this file except in compliance with the License.  You can obtain a copy
 269 in the file \s-1LICENSE\s0 in the source distribution or at
 270 <https://www.openssl.org/source/license.html>.