bin2c(1)

💖 bin2c — embed data files into C as variables 💖

okay so bestie, welcome to bin2c(1) from the hxtools girlies ✨ this one is genuinely iconic and also lowkey underrated, so let's get into it.

---

🌸 SYNTAX 🌸

bin2c [-C program-file] [-D dir_prefix] [-H header-file] [-G guard-name]
[-p num] [-v] [--ultra] [--wxbitmap] file...

like, that's the whole vibe check. files go in, C code comes out. periodt. 💅

---

🦋 DESCRIPTION 🦋

bin2c converts files to C variables. the way it does that is: it reads the contents of each file you hand it on the argument line, and then it writes out C program code that defines a variable holding that file's contents. no cap, that's the whole thing. 🫶

and like, the hxtools version of bin2c? it's the main character, because it supports:

• space-efficient encoding of the arbitrary data ✨
• multiple input files (yes queen, plural, bring your whole friend group) 💖
• creation of either a standalone .h file, or a .c/.h file pair. (peep the examples below, they explain it all.) 🎀

---

✨ OPTIONS ✨

• -C file — if you specify this, the variable definition gets emitted to the filename you gave. that's it, that's the girl.
• -D dir_prefix — every filename on the command line gets prefixed with the directory you pass. the implication here (and this is the important part, so listen up 🫶) is that files will be searched relative to dir_prefix, while the variable name that ends up in the C source for an image stays non-prefixed. so the path changes, the variable name doesn't. iykyk.
• -G name — you're requesting that an include guard with the identifier guard-name gets emitted into the header file. and heads up: if -C was specified and a .c/.h pair is generated, an include guard is always emitted, and then -G is the option you use to set that name. 💜
• -H file — the file where the variable declarations get emitted to. if -C was not specified, the h-file will not contain any header guard by default, and it will contain the variable definition, the latter of which will be marked as static (file scope). okay so that's a whole thing, just roll with it.
• -p num — strip num leading path components when transforming input paths to variable names. and if num is negative, that many trailing path components are retained instead. if -p isn't specified at all, the default is -1. 🍓
• -v — be verbose, bestie. show all the names and filenames that bin2c will write. not me wanting to see everything. 👑
• --ultra — write out the raw data as a string literal. ⚠️ but here's the catch and it's a real one: as the literal contains a trailing NUL byte, the size of the array is necessarily also one byte longer than the raw data, which you need to account for. (in C, it would be possible to write char x[3] = "ABC", but this leads to an error in C++ where x[4] is required.) so like, mind the gap, it's giving off-by-one energy 😭
• --wxbitmap — generate C++ code that generates wxBitmap objects. (this implies Ultra encoding, and deals with it appropriately, too.) fancy fr fr 🌈

---

🌟 EXAMPLES 🌟

so if you want to generate a single C header file that behaves like XPM files and which is suitable for inclusion into a C program file of your own, you go:

bin2c -H images.h foo.png bar.png

and if you want a .c/.h pair instead, the invocation is:

bin2c -C images.c foo.png bar.png

this will create a C program file "images.c" containing all the definitions and a "images.h" that your code can use to get ahold of the declarations. two files, one slay. 💅✨

---

💀 HISTORY 💀

fun fact for the lore girlies: hxtools's bin2c developed from the earlier png2wx.pl utility. glow-up of the century honestly. 🦋

---

🎀 SEE ALSO 🎀

• hxtools(7)

---

and that's the whole page bestie!! this one came from hxtools and it's dated 2013-09-29 — thank you for coming to my ted talk, go embed some files, mwah 💖🫶✨🎀