xref: /onnv-gate/usr/src/common/openssl/doc/crypto/BIO_ctrl.pod (revision 2175:b0b2f052a486)
1*2175Sjp161948=pod
2*2175Sjp161948
3*2175Sjp161948=head1 NAME
4*2175Sjp161948
5*2175Sjp161948BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
6*2175Sjp161948BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
7*2175Sjp161948BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
8*2175Sjp161948BIO_get_info_callback, BIO_set_info_callback - BIO control operations
9*2175Sjp161948
10*2175Sjp161948=head1 SYNOPSIS
11*2175Sjp161948
12*2175Sjp161948 #include <openssl/bio.h>
13*2175Sjp161948
14*2175Sjp161948 long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);
15*2175Sjp161948 long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));
16*2175Sjp161948 char *	BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
17*2175Sjp161948 long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);
18*2175Sjp161948
19*2175Sjp161948 int BIO_reset(BIO *b);
20*2175Sjp161948 int BIO_seek(BIO *b, int ofs);
21*2175Sjp161948 int BIO_tell(BIO *b);
22*2175Sjp161948 int BIO_flush(BIO *b);
23*2175Sjp161948 int BIO_eof(BIO *b);
24*2175Sjp161948 int BIO_set_close(BIO *b,long flag);
25*2175Sjp161948 int BIO_get_close(BIO *b);
26*2175Sjp161948 int BIO_pending(BIO *b);
27*2175Sjp161948 int BIO_wpending(BIO *b);
28*2175Sjp161948 size_t BIO_ctrl_pending(BIO *b);
29*2175Sjp161948 size_t BIO_ctrl_wpending(BIO *b);
30*2175Sjp161948
31*2175Sjp161948 int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
32*2175Sjp161948 int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
33*2175Sjp161948
34*2175Sjp161948 typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
35*2175Sjp161948
36*2175Sjp161948=head1 DESCRIPTION
37*2175Sjp161948
38*2175Sjp161948BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl()
39*2175Sjp161948are BIO "control" operations taking arguments of various types.
40*2175Sjp161948These functions are not normally called directly, various macros
41*2175Sjp161948are used instead. The standard macros are described below, macros
42*2175Sjp161948specific to a particular type of BIO are described in the specific
43*2175Sjp161948BIOs manual page as well as any special features of the standard
44*2175Sjp161948calls.
45*2175Sjp161948
46*2175Sjp161948BIO_reset() typically resets a BIO to some initial state, in the case
47*2175Sjp161948of file related BIOs for example it rewinds the file pointer to the
48*2175Sjp161948start of the file.
49*2175Sjp161948
50*2175Sjp161948BIO_seek() resets a file related BIO's (that is file descriptor and
51*2175Sjp161948FILE BIOs) file position pointer to B<ofs> bytes from start of file.
52*2175Sjp161948
53*2175Sjp161948BIO_tell() returns the current file position of a file related BIO.
54*2175Sjp161948
55*2175Sjp161948BIO_flush() normally writes out any internally buffered data, in some
56*2175Sjp161948cases it is used to signal EOF and that no more data will be written.
57*2175Sjp161948
58*2175Sjp161948BIO_eof() returns 1 if the BIO has read EOF, the precise meaning of
59*2175Sjp161948"EOF" varies according to the BIO type.
60*2175Sjp161948
61*2175Sjp161948BIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can
62*2175Sjp161948take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used
63*2175Sjp161948in a source/sink BIO to indicate that the underlying I/O stream should
64*2175Sjp161948be closed when the BIO is freed.
65*2175Sjp161948
66*2175Sjp161948BIO_get_close() returns the BIOs close flag.
67*2175Sjp161948
68*2175Sjp161948BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
69*2175Sjp161948return the number of pending characters in the BIOs read and write buffers.
70*2175Sjp161948Not all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending()
71*2175Sjp161948return a size_t type and are functions, BIO_pending() and BIO_wpending() are
72*2175Sjp161948macros which call BIO_ctrl().
73*2175Sjp161948
74*2175Sjp161948=head1 RETURN VALUES
75*2175Sjp161948
76*2175Sjp161948BIO_reset() normally returns 1 for success and 0 or -1 for failure. File
77*2175Sjp161948BIOs are an exception, they return 0 for success and -1 for failure.
78*2175Sjp161948
79*2175Sjp161948BIO_seek() and BIO_tell() both return the current file position on success
80*2175Sjp161948and -1 for failure, except file BIOs which for BIO_seek() always return 0
81*2175Sjp161948for success and -1 for failure.
82*2175Sjp161948
83*2175Sjp161948BIO_flush() returns 1 for success and 0 or -1 for failure.
84*2175Sjp161948
85*2175Sjp161948BIO_eof() returns 1 if EOF has been reached 0 otherwise.
86*2175Sjp161948
87*2175Sjp161948BIO_set_close() always returns 1.
88*2175Sjp161948
89*2175Sjp161948BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
90*2175Sjp161948
91*2175Sjp161948BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
92*2175Sjp161948return the amount of pending data.
93*2175Sjp161948
94*2175Sjp161948=head1 NOTES
95*2175Sjp161948
96*2175Sjp161948BIO_flush(), because it can write data may return 0 or -1 indicating
97*2175Sjp161948that the call should be retried later in a similar manner to BIO_write().
98*2175Sjp161948The BIO_should_retry() call should be used and appropriate action taken
99*2175Sjp161948is the call fails.
100*2175Sjp161948
101*2175Sjp161948The return values of BIO_pending() and BIO_wpending() may not reliably
102*2175Sjp161948determine the amount of pending data in all cases. For example in the
103*2175Sjp161948case of a file BIO some data may be available in the FILE structures
104*2175Sjp161948internal buffers but it is not possible to determine this in a
105*2175Sjp161948portably way. For other types of BIO they may not be supported.
106*2175Sjp161948
107*2175Sjp161948Filter BIOs if they do not internally handle a particular BIO_ctrl()
108*2175Sjp161948operation usually pass the operation to the next BIO in the chain.
109*2175Sjp161948This often means there is no need to locate the required BIO for
110*2175Sjp161948a particular operation, it can be called on a chain and it will
111*2175Sjp161948be automatically passed to the relevant BIO. However this can cause
112*2175Sjp161948unexpected results: for example no current filter BIOs implement
113*2175Sjp161948BIO_seek(), but this may still succeed if the chain ends in a FILE
114*2175Sjp161948or file descriptor BIO.
115*2175Sjp161948
116*2175Sjp161948Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl()
117*2175Sjp161948operation.
118*2175Sjp161948
119*2175Sjp161948=head1 BUGS
120*2175Sjp161948
121*2175Sjp161948Some of the return values are ambiguous and care should be taken. In
122*2175Sjp161948particular a return value of 0 can be returned if an operation is not
123*2175Sjp161948supported, if an error occurred, if EOF has not been reached and in
124*2175Sjp161948the case of BIO_seek() on a file BIO for a successful operation.
125*2175Sjp161948
126*2175Sjp161948=head1 SEE ALSO
127*2175Sjp161948
128*2175Sjp161948TBA
129