Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_s_fd.3
1 .rn '' }`
2 ''' $RCSfile$$Revision$$Date$
3 '''
4 ''' $Log$
5 '''
6 .de Sh
7 .br
8 .if t .Sp
9 .ne 5
10 .PP
11 \fB\\$1\fR
12 .PP
13 ..
14 .de Sp
15 .if t .sp .5v
16 .if n .sp
17 ..
18 .de Ip
19 .br
20 .ie \\n(.$>=3 .ne \\$3
21 .el .ne 3
22 .IP "\\$1" \\$2
23 ..
24 .de Vb
25 .ft CW
26 .nf
27 .ne \\$1
28 ..
29 .de Ve
30 .ft R
31
32 .fi
33 ..
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 '''
40 .tr \(*W-|\(bv\*(Tr
41 .ie n \{\
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' '
62 'br\}
63 .el\{\
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
79 'br\}
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"
92 ..
93 .nr % 0
94 .rr F
95 .\}
96 .TH BIO_s_fd 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97 .UC
98 .if n .hy 0
99 .if n .na
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
112 .bd B 3
113 .       \" fudge factors for nroff and troff
114 .if n \{\
115 .       ds #H 0
116 .       ds #V .8m
117 .       ds #F .3m
118 .       ds #[ \f1
119 .       ds #] \fP
120 .\}
121 .if t \{\
122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123 .       ds #V .6m
124 .       ds #F 0
125 .       ds #[ \&
126 .       ds #] \&
127 .\}
128 .       \" simple accents for nroff and troff
129 .if n \{\
130 .       ds ' \&
131 .       ds ` \&
132 .       ds ^ \&
133 .       ds , \&
134 .       ds ~ ~
135 .       ds ? ?
136 .       ds ! !
137 .       ds /
138 .       ds q
139 .\}
140 .if t \{\
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'
150 .\}
151 .       \" troff and (daisy-wheel) nroff accents
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'
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'\*(#]
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
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
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'
170 .       \" for low resolution devices (crt and lpr)
171 .if \n(.H>23 .if \n(.V>19 \
172 \{\
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
188 .\}
189 .rm #[ #] #H #V #F C
190 .SH "NAME"
191 BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd \- file descriptor BIO
192 .SH "SYNOPSIS"
193 .PP
194 .Vb 1
195 \& #include <openssl/bio.h>
196 .Ve
197 .Vb 1
198 \& BIO_METHOD *   BIO_s_fd(void);
199 .Ve
200 .Vb 2
201 \& #define BIO_set_fd(b,fd,c)     BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
202 \& #define BIO_get_fd(b,c)        BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
203 .Ve
204 .Vb 1
205 \& BIO *BIO_new_fd(int fd, int close_flag);
206 .Ve
207 .SH "DESCRIPTION"
208 \fIBIO_s_fd()\fR returns the file descriptor BIO method. This is a wrapper
209 round the platforms file descriptor routines such as \fIread()\fR and \fIwrite()\fR.
210 .PP
211 \fIBIO_read()\fR and \fIBIO_write()\fR read or write the underlying descriptor.
212 \fIBIO_puts()\fR is supported but \fIBIO_gets()\fR is not.
213 .PP
214 If the close flag is set then then \fIclose()\fR is called on the underlying
215 file descriptor when the BIO is freed.
216 .PP
217 \fIBIO_reset()\fR attempts to change the file pointer to the start of file
218 using \fIlseek\fR\|(fd, 0, 0).
219 .PP
220 \fIBIO_seek()\fR sets the file pointer to position \fBofs\fR from start of file
221 using \fIlseek\fR\|(fd, ofs, 0).
222 .PP
223 \fIBIO_tell()\fR returns the current file position by calling \fIlseek\fR\|(fd, 0, 1).
224 .PP
225 \fIBIO_set_fd()\fR sets the file descriptor of BIO \fBb\fR to \fBfd\fR and the close
226 flag to \fBc\fR.
227 .PP
228 \fIBIO_get_fd()\fR places the file descriptor in \fBc\fR if it is not NULL, it also
229 returns the file descriptor. If \fBc\fR is not NULL it should be of type
230 (int *).
231 .PP
232 \fIBIO_new_fd()\fR returns a file descriptor BIO using \fBfd\fR and \fBclose_flag\fR.
233 .SH "NOTES"
234 The behaviour of \fIBIO_read()\fR and \fIBIO_write()\fR depends on the behavior of the
235 platforms \fIread()\fR and \fIwrite()\fR calls on the descriptor. If the underlying 
236 file descriptor is in a non blocking mode then the BIO will behave in the
237 manner described in the BIO_read(3) and BIO_should_retry(3)
238 manual pages.
239 .PP
240 File descriptor BIOs should not be used for socket I/O. Use socket BIOs
241 instead.
242 .SH "RETURN VALUES"
243 \fIBIO_s_fd()\fR returns the file descriptor BIO method.
244 .PP
245 \fIBIO_reset()\fR returns zero for success and \-1 if an error occurred.
246 \fIBIO_seek()\fR and \fIBIO_tell()\fR return the current file position or \-1
247 is an error occurred. These values reflect the underlying \fIlseek()\fR
248 behaviour.
249 .PP
250 \fIBIO_set_fd()\fR always returns 1.
251 .PP
252 \fIBIO_get_fd()\fR returns the file descriptor or \-1 if the BIO has not
253 been initialized.
254 .PP
255 \fIBIO_new_fd()\fR returns the newly allocated BIO or NULL is an error
256 occurred.
257 .SH "EXAMPLE"
258 This is a file descriptor BIO version of \*(L"Hello World":
259 .PP
260 .Vb 4
261 \& BIO *out;
262 \& out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
263 \& BIO_printf(out, "Hello World\en");
264 \& BIO_free(out);
265 .Ve
266 .SH "SEE ALSO"
267 BIO_seek(3), BIO_tell(3),
268 BIO_reset(3), BIO_read(3),
269 BIO_write(3), BIO_puts(3),
270 BIO_gets(3), BIO_printf(3),
271 BIO_set_close(3), BIO_get_close(3)
272
273 .rn }` ''
274 .IX Title "BIO_s_fd 3"
275 .IX Name "BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO"
276
277 .IX Header "NAME"
278
279 .IX Header "SYNOPSIS"
280
281 .IX Header "DESCRIPTION"
282
283 .IX Header "NOTES"
284
285 .IX Header "RETURN VALUES"
286
287 .IX Header "EXAMPLE"
288
289 .IX Header "SEE ALSO"
290