---
name: "libressl-BIO_s_file"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-BIO_s_file"
---

# libressl-BIO\_s\_file(3)

FILE BIO

## NAME

**BIO\_s\_file**, **BIO\_new\_file**, **BIO\_new\_fp**, **BIO\_set\_fp**, **BIO\_get\_fp**, **BIO\_read\_filename**, **BIO\_write\_filename**, **BIO\_append\_filename**, **BIO\_rw\_filename** – FILE BIO

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

**#include \<openssl/bio.h\>**

*const* *BIO\_METHOD* *\**\

**BIO\_s\_file**(*void*);

*BIO* *\**\

**BIO\_new\_file**(*const char \*filename*, *const char \*mode*);

*BIO* *\**\

**BIO\_new\_fp**(*FILE \*stream*, *int flags*);

*long*\

**BIO\_set\_fp**(*BIO \*b*, *FILE \*fp*, *int flags*);

*long*\

**BIO\_get\_fp**(*BIO \*b*, *FILE \*\*fpp*);

*long*\

**BIO\_read\_filename**(*BIO \*b*, *char \*name*);

*long*\

**BIO\_write\_filename**(*BIO \*b*, *char \*name*);

*long*\

**BIO\_append\_filename**(*BIO \*b*, *char \*name*);

*long*\

**BIO\_rw\_filename**(*BIO \*b*, *char \*name*);

## DESCRIPTION

**BIO\_s\_file**() returns the BIO file method. As its name implies, it is a wrapper around the stdio *FILE* structure and it is a source/sink BIO.

Calls to BIO\_read(3) and BIO\_write(3) read and write data to the underlying stream. BIO\_gets(3) and BIO\_puts(3) are supported on file BIOs.

BIO\_flush(3) on a file BIO calls the [fflush(3)](/fflush/3.md) function on the wrapped stream.

BIO\_reset(3) attempts to change the file pointer to the start of file using **fseek**(*stream*, *0*, *0*).

BIO\_seek(3) sets the file pointer to position *ofs* from the start of the file using **fseek**(*stream*, *ofs*, *0*).

BIO\_eof(3) calls [feof(3)](/feof/3.md).

Setting the BIO\_CLOSE flag calls [fclose(3)](/fclose/3.md) on the stream when the BIO is freed.

**BIO\_new\_file**() creates a new file BIO with mode *mode*. The meaning of *mode* is the same as for the stdio function [fopen(3)](/fopen/3.md). The BIO\_CLOSE flag is set on the returned BIO.

**BIO\_new\_fp**() creates a file BIO wrapping *stream*. Flags can be: BIO\_CLOSE, BIO\_NOCLOSE (the close flag), BIO\_FP\_TEXT (sets the underlying stream to text mode, default is binary: this only has any effect under Win32).

**BIO\_set\_fp**() sets the file pointer of a file BIO to *fp*. *flags* has the same meaning as in **BIO\_new\_fp**().

**BIO\_get\_fp**() retrieves the file pointer of a file BIO.

BIO\_seek(3) sets the position pointer to *offset* bytes from the start of file.

BIO\_tell(3) returns the value of the position pointer.

**BIO\_read\_filename**(), **BIO\_write\_filename**(), **BIO\_append\_filename**(), and **BIO\_rw\_filename**() set the file BIO *b* to use file *name* for reading, writing, append or read write respectively.

When wrapping stdout, stdin, or stderr, the underlying stream should not normally be closed, so the BIO\_NOCLOSE flag should be set.

Because the file BIO calls the underlying stdio functions, any quirks in stdio behaviour will be mirrored by the corresponding BIO.

On Windows, **BIO\_new\_files**() reserves for the filename argument to be UTF-8 encoded. In other words, if you have to make it work in a multi-lingual environment, encode file names in UTF-8.

The following BIO\_ctrl(3) *cmd* constants correspond to macros:

| | |
| --- | --- |
| *cmd* constant | corresponding macro |
| BIO\_C\_FILE\_SEEK | BIO\_seek(3) |
| BIO\_C\_FILE\_TELL | BIO\_tell(3) |
| BIO\_C\_GET\_FILE\_PTR | **BIO\_get\_fp**() |
| BIO\_C\_SET\_FILE\_PTR | **BIO\_set\_fp**() |
| BIO\_C\_SET\_FILENAME | various, see below |
| BIO\_CTRL\_EOF | BIO\_eof(3) |
| BIO\_CTRL\_FLUSH | BIO\_flush(3) |
| BIO\_CTRL\_GET\_CLOSE | BIO\_get\_close(3) |
| BIO\_CTRL\_RESET | BIO\_reset(3) |
| BIO\_CTRL\_SET\_CLOSE | BIO\_set\_close(3) |

The meaning of BIO\_C\_SET\_FILENAME depends on the flags passed in the BIO\_ctrl(3) *larg* argument:

| | |
| --- | --- |
| *larg* argument | corresponding macro |
| BIO\_CLOSE \| BIO\_FP\_READ | **BIO\_read\_filename**() |
| BIO\_CLOSE \| BIO\_FP\_WRITE | **BIO\_write\_filename**() |
| BIO\_CLOSE \| BIO\_FP\_APPEND | **BIO\_append\_filename**() |
| BIO\_CLOSE \| BIO\_FP\_READ \| BIO\_FP\_WRITE | **BIO\_rw\_filename**() |

## RETURN VALUES

**BIO\_s\_file**() returns the file BIO method.

**BIO\_new\_file**() and **BIO\_new\_fp**() return a file BIO or NULL if an error occurred.

When called on a file BIO object, BIO\_method\_type(3) returns the constant BIO\_TYPE\_FILE and BIO\_method\_name(3) returns a pointer to the static string "FILE pointer".

**BIO\_set\_fp**() and **BIO\_get\_fp**() return 1 for success or 0 for failure (although the current implementation never returns 0).

BIO\_seek(3) returns the same value as the underlying [fseek(3)](/fseek/3.md) function: 0 for success or -1 for failure.

BIO\_tell(3) returns the current file position.

**BIO\_read\_filename**(), **BIO\_write\_filename**(), **BIO\_append\_filename**(), and **BIO\_rw\_filename**() return 1 for success or 0 for failure.

## EXAMPLES

File BIO "hello world":

```
BIO *bio_out;
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_printf(bio_out, "Hello World\n");
```

Alternative technique:

```
BIO *bio_out;
bio_out = BIO_new(BIO_s_file());
if(bio_out == NULL) /* Error ... */
if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
BIO_printf(bio_out, "Hello World\n");
```

Write to a file:

```
BIO *out;
out = BIO_new_file("filename.txt", "w");
if(!out) /* Error occurred */
BIO_printf(out, "Hello World\n");
BIO_free(out);
```

Alternative technique:

```
BIO *out;
out = BIO_new(BIO_s_file());
if(out == NULL) /* Error ... */
if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
BIO_printf(out, "Hello World\n");
BIO_free(out);
```

## SEE ALSO

BIO\_new(3), BIO\_read(3), BIO\_seek(3)

## HISTORY

**BIO\_s\_file**(), **BIO\_set\_fp**(), **BIO\_get\_fp**(), **BIO\_read\_filename**(), **BIO\_write\_filename**(), and **BIO\_append\_filename**() first appeared in SSLeay 0.6.0. **BIO\_new\_file**() and **BIO\_new\_fp**() first appeared in SSLeay 0.8.0. All these functions have been available since OpenBSD 2.4.

**BIO\_rw\_filename**() first appeared in SSLeay 0.9.1 and has been available since OpenBSD 2.6.

## BUGS

BIO\_reset(3) and BIO\_seek(3) are implemented using [fseek(3)](/fseek/3.md) on the underlying stream. The return value for [fseek(3)](/fseek/3.md) is 0 for success or -1 if an error occurred. This differs from other types of BIO which will typically return 1 for success and a non-positive value if an error occurred.