secure/lib/libcrypto/man/ASYNC_WAIT_CTX_new.3

   1 .\" Automatically generated by Pod::Man 4.09 (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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "ASYNC_WAIT_CTX_NEW 3"
 132 .TH ASYNC_WAIT_CTX_NEW 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/async.h>
 143 \&
 144 \& ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
 145 \& void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
 146 \& int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
 147 \&                                OSSL_ASYNC_FD fd,
 148 \&                                void *custom_data,
 149 \&                                void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
 150 \&                                                OSSL_ASYNC_FD, void *));
 151 \& int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
 152 \&                           OSSL_ASYNC_FD *fd, void **custom_data);
 153 \& int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
 154 \&                                size_t *numfds);
 155 \& int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
 156 \&                                    size_t *numaddfds, OSSL_ASYNC_FD *delfd,
 157 \&                                    size_t *numdelfds);
 158 \& int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
 159 .Ve
 160 .SH "DESCRIPTION"
 161 .IX Header "DESCRIPTION"
 162 For an overview of how asynchronous operations are implemented in OpenSSL see
 163 \&\fIASYNC_start_job\fR\|(3). An \s-1ASYNC_WAIT_CTX\s0 object represents an asynchronous
 164 \&\*(L"session\*(R", i.e. a related set of crypto operations. For example in \s-1SSL\s0 terms
 165 this would have a one-to-one correspondence with an \s-1SSL\s0 connection.
 166 .PP
 167 Application code must create an \s-1ASYNC_WAIT_CTX\s0 using the \fIASYNC_WAIT_CTX_new()\fR
 168 function prior to calling \fIASYNC_start_job()\fR (see \fIASYNC_start_job\fR\|(3)). When
 169 the job is started it is associated with the \s-1ASYNC_WAIT_CTX\s0 for the duration of
 170 that job. An \s-1ASYNC_WAIT_CTX\s0 should only be used for one \s-1ASYNC_JOB\s0 at any one
 171 time, but can be reused after an \s-1ASYNC_JOB\s0 has finished for a subsequent
 172 \&\s-1ASYNC_JOB.\s0 When the session is complete (e.g. the \s-1SSL\s0 connection is closed),
 173 application code cleans up with \fIASYNC_WAIT_CTX_free()\fR.
 174 .PP
 175 ASYNC_WAIT_CTXs can have \*(L"wait\*(R" file descriptors associated with them. Calling
 176 \&\fIASYNC_WAIT_CTX_get_all_fds()\fR and passing in a pointer to an \s-1ASYNC_WAIT_CTX\s0 in
 177 the \fBctx\fR parameter will return the wait file descriptors associated with that
 178 job in \fB*fd\fR. The number of file descriptors returned will be stored in
 179 \&\fB*numfds\fR. It is the caller's responsibility to ensure that sufficient memory
 180 has been allocated in \fB*fd\fR to receive all the file descriptors. Calling
 181 \&\fIASYNC_WAIT_CTX_get_all_fds()\fR with a \s-1NULL\s0 \fBfd\fR value will return no file
 182 descriptors but will still populate \fB*numfds\fR. Therefore application code is
 183 typically expected to call this function twice: once to get the number of fds,
 184 and then again when sufficient memory has been allocated. If only one
 185 asynchronous engine is being used then normally this call will only ever return
 186 one fd. If multiple asynchronous engines are being used then more could be
 187 returned.
 188 .PP
 189 The function \fIASYNC_WAIT_CTX_get_changed_fds()\fR can be used to detect if any fds
 190 have changed since the last call time \fIASYNC_start_job()\fR returned an \s-1ASYNC_PAUSE\s0
 191 result (or since the \s-1ASYNC_WAIT_CTX\s0 was created if no \s-1ASYNC_PAUSE\s0 result has
 192 been received). The \fBnumaddfds\fR and \fBnumdelfds\fR parameters will be populated
 193 with the number of fds added or deleted respectively. \fB*addfd\fR and \fB*delfd\fR
 194 will be populated with the list of added and deleted fds respectively. Similarly
 195 to \fIASYNC_WAIT_CTX_get_all_fds()\fR either of these can be \s-1NULL,\s0 but if they are not
 196 \&\s-1NULL\s0 then the caller is responsible for ensuring sufficient memory is allocated.
 197 .PP
 198 Implementors of async aware code (e.g. engines) are encouraged to return a
 199 stable fd for the lifetime of the \s-1ASYNC_WAIT_CTX\s0 in order to reduce the \*(L"churn\*(R"
 200 of regularly changing fds \- although no guarantees of this are provided to
 201 applications.
 202 .PP
 203 Applications can wait for the file descriptor to be ready for \*(L"read\*(R" using a
 204 system function call such as select or poll (being ready for \*(L"read\*(R" indicates
 205 that the job should be resumed). If no file descriptor is made available then an
 206 application will have to periodically \*(L"poll\*(R" the job by attempting to restart it
 207 to see if it is ready to continue.
 208 .PP
 209 Async aware code (e.g. engines) can get the current \s-1ASYNC_WAIT_CTX\s0 from the job
 210 via \fIASYNC_get_wait_ctx\fR\|(3) and provide a file descriptor to use for waiting
 211 on by calling \fIASYNC_WAIT_CTX_set_wait_fd()\fR. Typically this would be done by an
 212 engine immediately prior to calling \fIASYNC_pause_job()\fR and not by end user code.
 213 An existing association with a file descriptor can be obtained using
 214 \&\fIASYNC_WAIT_CTX_get_fd()\fR and cleared using \fIASYNC_WAIT_CTX_clear_fd()\fR. Both of
 215 these functions requires a \fBkey\fR value which is unique to the async aware
 216 code.  This could be any unique value but a good candidate might be the
 217 \&\fB\s-1ENGINE\s0 *\fR for the engine. The \fBcustom_data\fR parameter can be any value, and
 218 will be returned in a subsequent call to \fIASYNC_WAIT_CTX_get_fd()\fR. The
 219 \&\fIASYNC_WAIT_CTX_set_wait_fd()\fR function also expects a pointer to a \*(L"cleanup\*(R"
 220 routine. This can be \s-1NULL\s0 but if provided will automatically get called when
 221 the \s-1ASYNC_WAIT_CTX\s0 is freed, and gives the engine the opportunity to close the
 222 fd or any other resources. Note: The \*(L"cleanup\*(R" routine does not get called if
 223 the fd is cleared directly via a call to \fIASYNC_WAIT_CTX_clear_fd()\fR.
 224 .PP
 225 An example of typical usage might be an async capable engine. User code would
 226 initiate cryptographic operations. The engine would initiate those operations
 227 asynchronously and then call \fIASYNC_WAIT_CTX_set_wait_fd()\fR followed by
 228 \&\fIASYNC_pause_job()\fR to return control to the user code. The user code can then
 229 perform other tasks or wait for the job to be ready by calling \*(L"select\*(R" or other
 230 similar function on the wait file descriptor. The engine can signal to the user
 231 code that the job should be resumed by making the wait file descriptor
 232 \&\*(L"readable\*(R". Once resumed the engine should clear the wake signal on the wait
 233 file descriptor.
 234 .SH "RETURN VALUES"
 235 .IX Header "RETURN VALUES"
 236 \&\fIASYNC_WAIT_CTX_new()\fR returns a pointer to the newly allocated \s-1ASYNC_WAIT_CTX\s0 or
 237 \&\s-1NULL\s0 on error.
 238 .PP
 239 ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
 240 ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on
 241 success or 0 on error.
 242 .SH "NOTES"
 243 .IX Header "NOTES"
 244 On Windows platforms the openssl/async.h header is dependent on some
 245 of the types customarily made available by including windows.h. The
 246 application developer is likely to require control over when the latter
 247 is included, commonly as one of the first included headers. Therefore
 248 it is defined as an application developer's responsibility to include
 249 windows.h prior to async.h.
 250 .SH "SEE ALSO"
 251 .IX Header "SEE ALSO"
 252 \&\fIcrypto\fR\|(7), \fIASYNC_start_job\fR\|(3)
 253 .SH "HISTORY"
 254 .IX Header "HISTORY"
 255 ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
 256 ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
 257 ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd were first added to
 258 OpenSSL 1.1.0.
 259 .SH "COPYRIGHT"
 260 .IX Header "COPYRIGHT"
 261 Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
 262 .PP
 263 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 264 this file except in compliance with the License.  You can obtain a copy
 265 in the file \s-1LICENSE\s0 in the source distribution or at
 266 <https://www.openssl.org/source/license.html>.