BIO_S_FD(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💅 NAME 💅

BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd — bestie, it's the file descriptor BIO 🎀

This is a page from the OpenSSL manual, section 3SSL, and it's giving "wrapping your raw file descriptors in a cozy little BIO blanket" energy 🦋

✨ SYNOPSIS ✨

#include <openssl/bio.h>

const BIO_METHOD *BIO_s_fd(void);

int BIO_set_fd(BIO *b, int fd, int c);
int BIO_get_fd(BIO *b, int *c);

BIO *BIO_new_fd(int fd, int close_flag);

🌸 DESCRIPTION 🌸

BIO_s_fd() hands you the file descriptor BIO method, periodt. It's basically a wrapper round the platform's file descriptor routines, like read() and write() 👑

BIO_read_ex() and BIO_write_ex() do the reading and writing on the underlying descriptor. BIO_puts()? Supported, slay. BIO_gets()? Not supported, sadly 😭

If the close flag is set, then close() gets called on the underlying file descriptor when the BIO is freed. So it cleans up after itself like the main character it is.

BIO_reset() tries to move the file pointer back to the start of the file, like by using lseek(fd, 0, 0).

BIO_seek() sets the file pointer to position ofs from start of file, like by using lseek(fd, ofs, 0).

BIO_tell() tells you the current file position, like by calling lseek(fd, 0, 1).

BIO_set_fd() sets the file descriptor of BIO b to fd, and the close flag to c.

BIO_get_fd() puts the file descriptor of BIO b into c — but only if it's not NULL, okay? — and it hands back the file descriptor too. Double duty, iconic.

BIO_new_fd() returns a file descriptor BIO using fd and close_flag. Build-a-BIO workshop 🧚

🫶 NOTES 🫶

The way BIO_read_ex() and BIO_write_ex() behave? Lowkey depends on how the platform's read() and write() calls behave on that descriptor. So if the underlying file descriptor is in a non blocking mode, then the BIO will behave however the BIO_read_ex(3) and BIO_should_retry(3) manual pages describe. Iykyk ✨

⚠️ File descriptor BIOs should not be used for socket I/O, bestie. Use socket BIOs instead. No cap, just use the right tool for the job 💀

Also, heads up: BIO_set_fd() and BIO_get_fd() are implemented as macros. Surprise! 🙈

💖 RETURN VALUES 💖

  • BIO_s_fd() returns the file descriptor BIO method.
  • BIO_set_fd() returns 1 on success, or <=0 for failure 😬
  • BIO_get_fd() returns the file descriptor, or -1 if the BIO has not been initialized. It also returns zero and negative values if some other error occurs.
  • BIO_new_fd() returns the newly allocated BIO, or NULL if an error occurred.

🌈 EXAMPLES 🌈

This is the file descriptor BIO version of "Hello World", and honestly it ate:

BIO *out;

out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
BIO_printf(out, "Hello World\n");
BIO_free(out);

👑 SEE ALSO 👑

BIO_seek(3), BIO_tell(3), BIO_reset(3), BIO_read_ex(3), BIO_write_ex(3), BIO_puts(3), BIO_gets(3), BIO_printf(3), BIO_set_close(3), BIO_get_close(3)

Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

That's the whole thing, bestie — version 4.0.3, dated 2026-09-29, straight from the BIO_S_FD(3SSL) page 💖 go read your file descriptors and slay ✨🦋💅

📦 where this page comes from