Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_ctrl.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH BIO_ctrl 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
192BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
193BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
74dab6c2 194BIO_get_info_callback, BIO_set_info_callback \- BIO control operations
984263bc 195.SH "SYNOPSIS"
74dab6c2 196.PP
984263bc
MD
197.Vb 1
198\& #include <openssl/bio.h>
199.Ve
200.Vb 4
201\& long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);
202\& long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));
203\& char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
204\& long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);
205.Ve
206.Vb 11
207\& int BIO_reset(BIO *b);
208\& int BIO_seek(BIO *b, int ofs);
209\& int BIO_tell(BIO *b);
210\& int BIO_flush(BIO *b);
211\& int BIO_eof(BIO *b);
212\& int BIO_set_close(BIO *b,long flag);
213\& int BIO_get_close(BIO *b);
214\& int BIO_pending(BIO *b);
215\& int BIO_wpending(BIO *b);
216\& size_t BIO_ctrl_pending(BIO *b);
217\& size_t BIO_ctrl_wpending(BIO *b);
218.Ve
219.Vb 2
220\& int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
221\& int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
222.Ve
223.Vb 1
224\& typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
225.Ve
226.SH "DESCRIPTION"
74dab6c2
JR
227\fIBIO_ctrl()\fR, \fIBIO_callback_ctrl()\fR, \fIBIO_ptr_ctrl()\fR and \fIBIO_int_ctrl()\fR
228are BIO \*(L"control\*(R" operations taking arguments of various types.
984263bc
MD
229These functions are not normally called directly, various macros
230are used instead. The standard macros are described below, macros
74dab6c2 231specific to a particular type of BIO are described in the specific
984263bc
MD
232BIOs manual page as well as any special features of the standard
233calls.
234.PP
74dab6c2 235\fIBIO_reset()\fR typically resets a BIO to some initial state, in the case
984263bc
MD
236of file related BIOs for example it rewinds the file pointer to the
237start of the file.
238.PP
74dab6c2
JR
239\fIBIO_seek()\fR resets a file related BIO's (that is file descriptor and
240FILE BIOs) file position pointer to \fBofs\fR bytes from start of file.
984263bc 241.PP
74dab6c2 242\fIBIO_tell()\fR returns the current file position of a file related BIO.
984263bc 243.PP
74dab6c2
JR
244\fIBIO_flush()\fR normally writes out any internally buffered data, in some
245cases it is used to signal EOF and that no more data will be written.
984263bc 246.PP
74dab6c2
JR
247\fIBIO_eof()\fR returns 1 if the BIO has read EOF, the precise meaning of
248\*(L"EOF\*(R" varies according to the BIO type.
984263bc 249.PP
74dab6c2
JR
250\fIBIO_set_close()\fR sets the BIO \fBb\fR close flag to \fBflag\fR. \fBflag\fR can
251take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used
252in a source/sink BIO to indicate that the underlying I/O stream should
253be closed when the BIO is freed.
984263bc 254.PP
74dab6c2 255\fIBIO_get_close()\fR returns the BIOs close flag.
984263bc 256.PP
74dab6c2 257\fIBIO_pending()\fR, \fIBIO_ctrl_pending()\fR, \fIBIO_wpending()\fR and \fIBIO_ctrl_wpending()\fR
984263bc
MD
258return the number of pending characters in the BIOs read and write buffers.
259Not all BIOs support these calls. \fIBIO_ctrl_pending()\fR and \fIBIO_ctrl_wpending()\fR
260return a size_t type and are functions, \fIBIO_pending()\fR and \fIBIO_wpending()\fR are
261macros which call \fIBIO_ctrl()\fR.
262.SH "RETURN VALUES"
74dab6c2 263\fIBIO_reset()\fR normally returns 1 for success and 0 or \-1 for failure. File
984263bc
MD
264BIOs are an exception, they return 0 for success and \-1 for failure.
265.PP
74dab6c2 266\fIBIO_seek()\fR and \fIBIO_tell()\fR both return the current file position on success
984263bc
MD
267and \-1 for failure, except file BIOs which for \fIBIO_seek()\fR always return 0
268for success and \-1 for failure.
269.PP
74dab6c2 270\fIBIO_flush()\fR returns 1 for success and 0 or \-1 for failure.
984263bc 271.PP
74dab6c2 272\fIBIO_eof()\fR returns 1 if EOF has been reached 0 otherwise.
984263bc 273.PP
74dab6c2 274\fIBIO_set_close()\fR always returns 1.
984263bc 275.PP
74dab6c2 276\fIBIO_get_close()\fR returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
984263bc 277.PP
74dab6c2 278\fIBIO_pending()\fR, \fIBIO_ctrl_pending()\fR, \fIBIO_wpending()\fR and \fIBIO_ctrl_wpending()\fR
984263bc
MD
279return the amount of pending data.
280.SH "NOTES"
74dab6c2 281\fIBIO_flush()\fR, because it can write data may return 0 or \-1 indicating
984263bc
MD
282that the call should be retried later in a similar manner to \fIBIO_write()\fR.
283The \fIBIO_should_retry()\fR call should be used and appropriate action taken
284is the call fails.
285.PP
286The return values of \fIBIO_pending()\fR and \fIBIO_wpending()\fR may not reliably
287determine the amount of pending data in all cases. For example in the
74dab6c2 288case of a file BIO some data may be available in the FILE structures
984263bc 289internal buffers but it is not possible to determine this in a
74dab6c2 290portably way. For other types of BIO they may not be supported.
984263bc
MD
291.PP
292Filter BIOs if they do not internally handle a particular \fIBIO_ctrl()\fR
74dab6c2
JR
293operation usually pass the operation to the next BIO in the chain.
294This often means there is no need to locate the required BIO for
984263bc 295a particular operation, it can be called on a chain and it will
74dab6c2 296be automatically passed to the relevant BIO. However this can cause
984263bc 297unexpected results: for example no current filter BIOs implement
74dab6c2
JR
298\fIBIO_seek()\fR, but this may still succeed if the chain ends in a FILE
299or file descriptor BIO.
984263bc
MD
300.PP
301Source/sink BIOs return an 0 if they do not recognize the \fIBIO_ctrl()\fR
302operation.
303.SH "BUGS"
984263bc
MD
304Some of the return values are ambiguous and care should be taken. In
305particular a return value of 0 can be returned if an operation is not
74dab6c2
JR
306supported, if an error occurred, if EOF has not been reached and in
307the case of \fIBIO_seek()\fR on a file BIO for a successful operation.
984263bc 308.SH "SEE ALSO"
74dab6c2
JR
309TBA
310
311.rn }` ''
312.IX Title "BIO_ctrl 3"
313.IX Name "BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
314BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
315BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
316BIO_get_info_callback, BIO_set_info_callback - BIO control operations"
317
318.IX Header "NAME"
319
320.IX Header "SYNOPSIS"
321
322.IX Header "DESCRIPTION"
323
324.IX Header "RETURN VALUES"
325
326.IX Header "NOTES"
327
328.IX Header "BUGS"
329
984263bc 330.IX Header "SEE ALSO"
74dab6c2 331