---
name: "libressl-BIO_ctrl"
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_ctrl"
---

# libressl-BIO\_ctrl(3)

BIO control operations

## NAME

**BIO\_ctrl**, **BIO\_callback\_ctrl**, **BIO\_ptr\_ctrl**, **BIO\_int\_ctrl**, **BIO\_reset**, **BIO\_seek**, **BIO\_tell**, **BIO\_flush**, **BIO\_eof**, **BIO\_set\_close**, **BIO\_get\_close**, **BIO\_pending**, **BIO\_wpending**, **BIO\_ctrl\_pending**, **BIO\_ctrl\_wpending**, **BIO\_get\_info\_callback**, **BIO\_set\_info\_callback**, **BIO\_info\_cb**, **bio\_info\_cb** – BIO control operations

## SYNOPSIS

Crypto Library (libcrypto, -lcrypto)

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

*long*\

**BIO\_ctrl**(*BIO \*b*, *int cmd*, *long larg*, *void \*parg*);

*long*\

**BIO\_callback\_ctrl**(*BIO \*b*, *int cmd*, *BIO\_info\_cb \*cb*);

*char* *\**\

**BIO\_ptr\_ctrl**(*BIO \*b*, *int cmd*, *long larg*);

*long*\

**BIO\_int\_ctrl**(*BIO \*b*, *int cmd*, *long larg*, *int iarg*);

*int*\

**BIO\_reset**(*BIO \*b*);

*int*\

**BIO\_seek**(*BIO \*b*, *int ofs*);

*int*\

**BIO\_tell**(*BIO \*b*);

*int*\

**BIO\_flush**(*BIO \*b*);

*int*\

**BIO\_eof**(*BIO \*b*);

*int*\

**BIO\_set\_close**(*BIO \*b*, *long flag*);

*int*\

**BIO\_get\_close**(*BIO \*b*);

*int*\

**BIO\_pending**(*BIO \*b*);

*int*\

**BIO\_wpending**(*BIO \*b*);

*size\_t*\

**BIO\_ctrl\_pending**(*BIO \*b*);

*size\_t*\

**BIO\_ctrl\_wpending**(*BIO \*b*);

*int*\

**BIO\_get\_info\_callback**(*BIO \*b*, *BIO\_info\_cb \*\*cbp*);

*int*\

**BIO\_set\_info\_callback**(*BIO \*b*, *BIO\_info\_cb \*cb*);

*typedef* *int*\

**BIO\_info\_cb**(*BIO \*b*, *int state*, *int res*);

*typedef* *int*\

**bio\_info\_cb**(*BIO \*b*, *int state*, *int res*);

## DESCRIPTION

**BIO\_ctrl**(), **BIO\_callback\_ctrl**(), **BIO\_ptr\_ctrl**(), and **BIO\_int\_ctrl**() are BIO "control" operations taking arguments of various types. These functions are not normally called directly - various macros are used instead. The standard macros are described below. Macros specific to a particular type of BIO are described in the specific BIO's manual page as well as any special features of the standard calls.

Depending on the *cmd* and on the type of *b*, **BIO\_ctrl**() may have a read-only effect on *b* or change data in *b* or in its sub-structures. It may also have a side effect of changing the memory pointed to by *parg*.

**BIO\_callback\_ctrl**() does not call **BIO\_ctrl**() but instead requires that the BIO type of *b* provides a dedicated *callback\_ctrl* function pointer, which is built into the library for some standard BIO types and can be provided with BIO\_meth\_set\_callback\_ctrl(3) for application-defined BIO types. The only *cmd* supported by **BIO\_callback\_ctrl**() is BIO\_CTRL\_SET\_CALLBACK.

**BIO\_ptr\_ctrl**() calls **BIO\_ctrl**() with *parg* pointing to the location of a temporary pointer variable initialized to NULL.

**BIO\_int\_ctrl**() calls **BIO\_ctrl**() with *parg* pointing to the location of a temporary *int* variable initialized to *iarg*. If **BIO\_ctrl**() changes the value stored at \**parg*, the new value is ignored.

**BIO\_reset**() typically resets a BIO to some initial state. In the case of file related BIOs, for example, it rewinds the file pointer to the start of the file.

**BIO\_seek**() resets a file related BIO's (that is file descriptor and FILE BIOs) file position pointer to *ofs* bytes from start of file.

**BIO\_tell**() returns the current file position of a file related BIO.

**BIO\_flush**() normally writes out any internally buffered data. In some cases it is used to signal EOF and that no more data will be written.

**BIO\_eof**() returns 1 if the BIO has read EOF. The precise meaning of "EOF" varies according to the BIO type.

**BIO\_set\_close**() sets the BIO *b* close flag to *flag*. *flag* can take the value BIO\_CLOSE or BIO\_NOCLOSE. Typically BIO\_CLOSE is used in a source/sink BIO to indicate that the underlying I/O stream should be closed when the BIO is freed.

**BIO\_get\_close**() returns the BIO's close flag.

**BIO\_pending**(), **BIO\_ctrl\_pending**(), **BIO\_wpending**(), and **BIO\_ctrl\_wpending**() return the number of pending characters in the BIO's read and write buffers. Not all BIOs support these calls. **BIO\_ctrl\_pending**() and **BIO\_ctrl\_wpending**() return a *size\_t* type and are functions.

**BIO\_set\_info\_callback**() installs the function pointer *cb* as an info callback in *b* by calling **BIO\_callback\_ctrl**() with a command of BIO\_CTRL\_SET\_CALLBACK. Among the BIO types built into the library, only BIO\_s\_connect(3) and BIO\_f\_ssl(3) support this functionality. Some filter BIO types forward this control call to the next BIO in the chain instead of processing it themselves.

**BIO\_get\_info\_callback**() places the function pointer to the info callback into \**cbp* if any was installed using **BIO\_set\_info\_callback**() or **BIO\_callback\_ctrl**(). If the type of *b* supports setting an info callback but none was installed, it stores a NULL pointer in \**cbp*.

The function type name *bio\_info\_cb* is a deprecated synonym for *BIO\_info\_cb* provided for backward compatibility with some existing application software.

The following *cmd* constants correspond to macros:

| | |
| --- | --- |
| *cmd* constant | corresponding macro |
| BIO\_C\_DESTROY\_BIO\_PAIR | BIO\_destroy\_bio\_pair(3) |
| BIO\_C\_DO\_STATE\_MACHINE | BIO\_do\_handshake(3) |
| BIO\_C\_FILE\_SEEK | **BIO\_seek**() |
| BIO\_C\_FILE\_TELL | **BIO\_tell**() |
| BIO\_C\_GET\_ACCEPT | BIO\_get\_accept\_port(3) |
| BIO\_C\_GET\_BIND\_MODE | BIO\_get\_bind\_mode(3) |
| BIO\_C\_GET\_BUF\_MEM\_PTR | BIO\_get\_mem\_ptr(3) |
| BIO\_C\_GET\_BUFF\_NUM\_LINES | BIO\_get\_buffer\_num\_lines(3) |
| BIO\_C\_GET\_CIPHER\_CTX | BIO\_get\_cipher\_ctx(3) |
| BIO\_C\_GET\_CIPHER\_STATUS | BIO\_get\_cipher\_status(3) |
| BIO\_C\_GET\_FD | BIO\_get\_fd(3) |
| BIO\_C\_GET\_FILE\_PTR | BIO\_get\_fp(3) |
| BIO\_C\_GET\_MD | BIO\_get\_md(3) |
| BIO\_C\_GET\_MD\_CTX | BIO\_get\_md\_ctx(3) |
| BIO\_C\_GET\_READ\_REQUEST | BIO\_get\_read\_request(3) |
| BIO\_C\_GET\_SSL | BIO\_get\_ssl(3) |
| BIO\_C\_GET\_SSL\_NUM\_RENEGOTIATES | BIO\_get\_num\_renegotiates(3) |
| BIO\_C\_GET\_WRITE\_BUF\_SIZE | BIO\_get\_write\_buf\_size(3) |
| BIO\_C\_GET\_WRITE\_GUARANTEE | BIO\_get\_write\_guarantee(3) |
| BIO\_C\_MAKE\_BIO\_PAIR | BIO\_make\_bio\_pair(3) |
| BIO\_C\_RESET\_READ\_REQUEST | BIO\_ctrl\_reset\_read\_request(3) |
| BIO\_C\_SET\_BIND\_MODE | BIO\_set\_bind\_mode(3) |
| BIO\_C\_SET\_BUF\_MEM | BIO\_set\_mem\_buf(3) |
| BIO\_C\_SET\_BUF\_MEM\_EOF\_RETURN | BIO\_set\_mem\_eof\_return(3) |
| BIO\_C\_SET\_BUFF\_READ\_DATA | BIO\_set\_buffer\_read\_data(3) |
| BIO\_C\_SET\_FD | BIO\_set\_fd(3) |
| BIO\_C\_SET\_FILE\_PTR | BIO\_set\_fp(3) |
| BIO\_C\_SET\_MD | BIO\_set\_md(3) |
| BIO\_C\_SET\_MD\_CTX | BIO\_set\_md\_ctx(3) |
| BIO\_C\_SET\_NBIO | BIO\_set\_nbio(3) |
| BIO\_C\_SET\_SSL | BIO\_set\_ssl(3) |
| BIO\_C\_SET\_SSL\_RENEGOTIATE\_BYTES | BIO\_set\_ssl\_renegotiate\_bytes(3) |
| BIO\_C\_SET\_SSL\_RENEGOTIATE\_TIMEOUT | BIO\_set\_ssl\_renegotiate\_timeout(3) |
| BIO\_C\_SET\_WRITE\_BUF\_SIZE | BIO\_set\_write\_buf\_size(3) |
| BIO\_C\_SHUTDOWN\_WR | BIO\_shutdown\_wr(3) |
| BIO\_C\_SSL\_MODE | BIO\_set\_ssl\_mode(3) |
| BIO\_CTRL\_DGRAM\_CONNECT | BIO\_ctrl\_dgram\_connect(3) |
| BIO\_CTRL\_DGRAM\_GET\_PEER | BIO\_dgram\_get\_peer(3) |
| BIO\_CTRL\_DGRAM\_GET\_RECV\_TIMER\_EXP | BIO\_dgram\_recv\_timedout(3) |
| BIO\_CTRL\_DGRAM\_GET\_SEND\_TIMER\_EXP | BIO\_dgram\_send\_timedout(3) |
| BIO\_CTRL\_DGRAM\_SET\_CONNECTED | BIO\_ctrl\_set\_connected(3) |
| BIO\_CTRL\_DGRAM\_SET\_PEER | BIO\_dgram\_set\_peer(3) |
| BIO\_CTRL\_DUP | BIO\_dup\_state(3) |
| BIO\_CTRL\_EOF | **BIO\_eof**() |
| BIO\_CTRL\_FLUSH | **BIO\_flush**() |
| BIO\_CTRL\_GET\_CALLBACK | **BIO\_get\_info\_callback**() |
| BIO\_CTRL\_GET\_CLOSE | **BIO\_get\_close**() |
| BIO\_CTRL\_INFO | BIO\_get\_mem\_data(3) |
| BIO\_CTRL\_PENDING | **BIO\_pending**() |
| BIO\_CTRL\_RESET | **BIO\_reset**() |
| BIO\_CTRL\_SET\_CALLBACK | **BIO\_set\_info\_callback**() |
| BIO\_CTRL\_SET\_CLOSE | **BIO\_set\_close**() |
| BIO\_CTRL\_WPENDING | **BIO\_wpending**() |

A few *cmd* constants serve more than one macro each and are documented in the following manual pages:

| | |
| --- | --- |
| *cmd* constant | manual page |
| BIO\_C\_GET\_CONNECT | BIO\_s\_connect(3) |
| BIO\_C\_SET\_ACCEPT | BIO\_s\_accept(3) |
| BIO\_C\_SET\_BUFF\_SIZE | BIO\_f\_buffer(3) |
| BIO\_C\_SET\_CONNECT | BIO\_s\_connect(3) |
| BIO\_C\_SET\_FILENAME | BIO\_s\_file(3) |

Some *cmd* constants are not associated with any macros. They are documented in the following manual pages:

| | |
| --- | --- |
| *cmd* constant | manual page |
| BIO\_CTRL\_DGRAM\_GET\_FALLBACK\_MTU | BIO\_dgram\_set\_peer(3) |
| BIO\_CTRL\_DGRAM\_GET\_MTU | BIO\_dgram\_set\_peer(3) |
| BIO\_CTRL\_DGRAM\_GET\_RECV\_TIMEOUT | BIO\_dgram\_recv\_timedout(3) |
| BIO\_CTRL\_DGRAM\_GET\_SEND\_TIMEOUT | BIO\_dgram\_send\_timedout(3) |
| BIO\_CTRL\_DGRAM\_SET\_MTU | BIO\_dgram\_set\_peer(3) |
| BIO\_CTRL\_DGRAM\_SET\_NEXT\_TIMEOUT | BIO\_dgram\_recv\_timedout(3) |
| BIO\_CTRL\_DGRAM\_SET\_RECV\_TIMEOUT | BIO\_dgram\_recv\_timedout(3) |
| BIO\_CTRL\_DGRAM\_SET\_SEND\_TIMEOUT | BIO\_dgram\_send\_timedout(3) |
| BIO\_CTRL\_DGRAM\_MTU\_EXCEEDED | BIO\_s\_datagram(3) |
| BIO\_CTRL\_POP | BIO\_pop(3) |
| BIO\_CTRL\_PUSH | BIO\_push(3) |

## RETURN VALUES

The meaning of the return values of **BIO\_ctrl**(), **BIO\_callback\_ctrl**(), and **BIO\_int\_ctrl**() depends on both the type of *b* and on the *cmd*. If *b* is a NULL pointer, no action occurs and 0 is returned. The return value -2 usually indicates a fatal error. In particular, it is returned if the *cmd* is unsupported by the type of *b*.

**BIO\_callback\_ctrl**() and **BIO\_set\_info\_callback**() return 1 on success, 0 if *b* is NULL or to indicate failure of a valid *cmd*, or -2 if the *cmd* is not supported by *b*.

**BIO\_ptr\_ctrl**() returns NULL if the **BIO\_ctrl**() call returns a negative value or does not change \**parg*, or the pointer it puts into \**parg* otherwise.

**BIO\_int\_ctrl**() returns the return value of **BIO\_ctrl**().

**BIO\_reset**() normally returns 1 for success and 0 or -1 for failure. File BIOs are an exception, returning 0 for success and -1 for failure.

**BIO\_seek**() and **BIO\_tell**() both return the current file position on success and -1 for failure, except file BIOs which for **BIO\_seek**() always return 0 for success and -1 for failure.

**BIO\_flush**() returns 1 for success and 0 or -1 for failure.

**BIO\_eof**() returns 1 if EOF has been reached or 0 otherwise.

**BIO\_set\_close**() always returns 1.

**BIO\_get\_close**() returns the close flag value BIO\_CLOSE or BIO\_NOCLOSE.

**BIO\_pending**(), **BIO\_ctrl\_pending**(), **BIO\_wpending**(), and **BIO\_ctrl\_wpending**() return the amount of pending data.

**BIO\_get\_info\_callback**() returns 1 on success, including when the type of *b* supports an info callback but none is installed, 0 if *b* is NULL or -2 if the type of *b* does not support an info callback.

If a callback was installed in *b* using BIO\_set\_callback\_ex(3) or BIO\_set\_callback(3), it can modify the return values of all these functions.

## NOTES

Because it can write data, **BIO\_flush**() may return 0 or -1 indicating that the call should be retried later in a similar manner to BIO\_write(3). The BIO\_should\_retry(3) call should be used and appropriate action taken if the call fails.

The return values of **BIO\_pending**() and **BIO\_wpending**() may not reliably determine the amount of pending data in all cases. For example in the case of a file BIO some data may be available in the *FILE* structure's internal buffers but it is not possible to determine this in a portable way. For other types of BIO they may not be supported.

If they do not internally handle a particular **BIO\_ctrl**() operation, filter BIOs usually pass the operation to the next BIO in the chain. This often means there is no need to locate the required BIO for a particular operation: it can be called on a chain and it will be automatically passed to the relevant BIO. However, this can cause unexpected results. For example no current filter BIOs implement **BIO\_seek**(), but this may still succeed if the chain ends in a FILE or file descriptor BIO.

Source/sink BIOs return a 0 if they do not recognize the **BIO\_ctrl**() operation.

## SEE ALSO

BIO\_meth\_new(3), BIO\_new(3)

## HISTORY

**BIO\_ctrl**(), **BIO\_reset**(), **BIO\_flush**(), **BIO\_eof**(), **BIO\_set\_close**(), **BIO\_get\_close**(), and **BIO\_pending**() first appeared in SSLeay 0.6.0. **BIO\_wpending**() first appeared in SSLeay 0.8.1. **BIO\_ptr\_ctrl**(), **BIO\_int\_ctrl**(), **BIO\_get\_info\_callback**() and **BIO\_set\_info\_callback**() first appeared in SSLeay 0.9.0. All these functions have been available since OpenBSD 2.4.

**BIO\_seek**() and **BIO\_tell**() first appeared in SSLeay 0.9.1. **BIO\_ctrl\_pending**() and **BIO\_ctrl\_wpending**() first appeared in OpenSSL 0.9.4. These functions have been available since OpenBSD 2.6.

**BIO\_callback\_ctrl**() first appeared in OpenSSL 0.9.5 and has been available since OpenBSD 2.7.

**bio\_info\_cb**() first appeared with a more complicated prototype in OpenSSL 0.9.6 and has been available since OpenBSD 2.9.

**BIO\_info\_cb**() first appeared in OpenSSL 1.1.0h and has been available since OpenBSD 6.3.

## BUGS

Some of the return values are ambiguous and care should be taken. In particular a return value of 0 can be returned if an operation is not supported, if an error occurred, if EOF has not been reached and in the case of **BIO\_seek**() on a file BIO for a successful operation.