Fix warning in musl related to ioctl

Ioctl's in musl take ints, while glibc take unsigned longs. When not
using glibc, default to casting the ioctl number to an int. Tests
passing.

Makefile

@@ -21,4 +21,19 @@ clean:
 
 install: writeimg
 	install -d $(DESTDIR)$(PREFIX)/bin
+	install -d $(DESTDIR)$(PREFIX)/share/man/man1
 	install -m 0755 $< $(DESTDIR)$(PREFIX)/bin/$<
+	install -m 0644 $<.1 $(DESTDIR)$(PREFIX)/share/man/man1/$<.1
+
+# Note that this bypasses PREFIX, since
+# bash does not source /usr/local by default
+install_bash: writeimg_completion_bash.sh
+	install -d $(DESTDIR)/etc/bash_completion.d
+	install -m 0644 $< $(DESTDIR)/etc/bash_completion.d/$<
+
+uninstall:
+	rm -f $(DESTDIR)$(PREFIX)/bin/writeimg
+	rm -f $(DESTDIR)$(PREFIX)/share/man/man1/writeimg.1
+	rm -f $(DESTDIR)/etc/bash_completion.d/writeimg*
+
+.PHONY: clean install uninstall

README.md

@@ -1,13 +1,17 @@
-# Simple dd-like image writer with additional security checks.
+# WriteIMG Image Writer
 
-This tool verifies your image automatically. The block size is currently set to
-1 MiB, which should be enough to avoid trouble.
+WriteIMG is a simple dd-like image writer with additional security checks for
+Linux and soon FreeBSD. It tells you what you're about to do and warns you
+about potential problems before they occur. It also features automatic image
+verifications, and uses a suitable block size for fast and gentle writing.  
+
+Say goodbye to fried flash and overwritten bootloaders, no more footguns!
 
 ```
-writeimg v0.2.0, Rev. 5323932-dirty
+WriteIMG v0.2.3, Rev. d02fc5f
 In honor of SwePwnage - the OG disk destroyer
 Copyright (C) 2026 Imbus, BSD-2-Clause
-Build date: 2026-02-07
+Build date: 2026-02-21
 
 Usage:
    writeimg [-v] -d <device> <file.img>
@@ -17,12 +21,18 @@ Args:
    -v                  Verify only
    -d device           Target block device
    -h, --help          Print this help message
-   -n, --noconfirm     Do not ask for premission
+   -n, --noconfirm     Do not ask for permission
    -V, --version       Print version
 ```
 
+We also provide a manpage, which targets OpenBSD-level quality. Incorrect or
+outdated information is a bug.
+
 ## Testing
 
+For testing, there is a shell script "test.sh" included. It sets up a block dev
+and writes (and verifies) a bunch of nonsense to it. It boils down to:
+
 ```
 dd if=/dev/zero of=./disk.img bs=1M count=1024
 losetup -fP ./disk.img
@@ -30,6 +40,75 @@ losetup -a
 losedup -d /dev/loop0
 ```
 
+Writes to a regular files is not currently in scope, although it would simplify
+testing.
+
+## Design Considerations
+
+Most of the sanity checking is currently highly Linux specific. We should
+prefer general/posix solutions that reach **at least** FreeBSD, preferably
+OpenBSD and Solaris as well. FreeBSD did implement procfs, but its a Linux-ism
+and it has since been deprecated. I would prefer not to turn this rather simple
+code into macro-mozaic, as i've seen other similar projects do. After all, this
+is just a juiced-up dd-rewrite at its core.  
+
+**Apple products are unsupported.** Im simply not interested in ensuring
+compatibility with a walled-garden ecosystem. If *you* are, we can change that.  
+
+At the time of writing, my FreeBSD server is down for maintenance, which means
+all of my development and testing is focused on AMD64, AArch64 and AArch32
+Linux.  
+
+In the setup phase of the program, we can absolutely afford to do lots of
+sanity checking via syscalls. Between each block write, we flush the disk
+buffers. These flushes are larger (1 MiB when buffer is full) than the sector
+size (often 4k or 64k) of the flash, so as far as i know, this is a gentle way
+to write flash, and should not incur any significant performance overhead. 1
+MiB is also a multiple of the most common sector sizes. We could write it all
+with no flushing, but that would mean the progress indicator will measure
+buffered writes, which is useless.  
+
+It should be possible to induce optimal block size, but this idea has not been
+explored yet.  
+
+Currently when verifying the written data, we read from both the input file and
+the output block device and do a byte-by-byte comparison. A CRC32 is also
+calculated in the first pass of the input file read. In the second pass (the
+verification stage), we calculate the CRC32 of the block device data and
+compare that to our previous result. **This means that we currently use two
+separate methods of verification**. The program allocates **two** separate
+buffers in the startup phase for comparisons. This will change in the coming
+releases, and we will rely only on the CRC.  
+
+De-allocation is handled in the interrupt vector as well as in the 'sad-paths',
+but ultimately this program can be regarded as samurai-principled. We try to
+handle deallocation, but exit on failure and let the kernel handle the rest.  
+
+The use of a crypto-grade checksumming algorithm was considered, but was
+ultimately rejected in favour of a lookup based CRC32. Its simpler, faster and
+easier to understand (See: [crc32.h](./crc32.h)). We may include a compile-time
+option to disable the lookup table to reduce size for really small targets, but
+we speculate that those targets are already satisfied with busybox-dd.  
+
+We also considered using libudev or any of its analogues, to determine the type
+of block device (spinning or flash), but my somewhat inconclusive research
+indicates that it does not include functionality to determine the medium type
+(usb/sd/sata), which is ultimately what i would like to warn the user about.
+The libudev library is also Linux specific.  
+
+We also need completion scripts for the most common shells. This includes csh,
+bash and zsh. Should be easy enough when we set our minds to it.  
+
+See:
+ - `grep -nE 'BLK[A-Za-z0-9]+' /usr/include/linux/fs.h`  
+   In particular, we're interested in BLKGETSIZE64 and BLKFLSBUF for now.
+
+We can read the device info from:
+ - /sys/class/block/[name]/*
+Like:
+ - /sys/class/block/[name]/device/model
+ - /sys/class/block/[name]/size
+
 ## Inspiration
 
 See:

test.sh

@@ -0,0 +1,72 @@
+#!/usr/env/bin bash
+
+set -e
+# set -x # For debugging
+
+# If you ever mess this up:
+#  $ mknod /dev/loop-control c 10 237
+#  $ chmod 600 /dev/loop-control
+#  $ chown root:root /dev/loop-control
+#
+# For cleanup:
+#  $ find /dev -maxdepth 1 -type b -name 'loop[0-9]*' -exec rm -f {} \;
+
+if [ "$(id -u)" -ne 0 ]; then
+    echo "Run as root. We need permissions to write and setup a loop device."
+    exit 1
+fi
+
+DISKFILE="/tmp/disk.img"
+BINFILE="/tmp/file.bin"
+LOOPNUM=$((RANDOM % 156 + 100))
+LOOPDEV="/dev/loop${LOOPNUM}"
+
+echo "Using device: ${LOOPDEV}"
+
+cleanup() {
+    echo "Cleaning up..."
+    set +e -x
+    losetup -d ${LOOPDEV}
+    rm ${LOOPDEV}
+    rm ${BINFILE} ${DISKFILE}
+}
+
+trap cleanup EXIT INT TERM
+
+if losetup ${LOOPDEV} >/dev/null 2>&1; then
+    echo "${LOOPDEV} already in use" >&2
+    cleanup
+    exit 1
+fi
+
+if [ ! -f ${DISKFILE} ]; then
+    echo "Creating ${DISKFILE}"
+    dd if=/dev/zero of=${DISKFILE} bs=1M count=256
+fi
+
+if [ ! -f ${BINFILE} ]; then
+    echo "Creating ${BINFILE}"
+    dd if=/dev/urandom of=${BINFILE} bs=1M count=64
+fi
+
+if [ ! -e ${LOOPDEV} ]; then
+    mknod ${LOOPDEV} b 7 ${LOOPNUM} # busybox needs this
+    losetup ${LOOPDEV} ${DISKFILE}
+fi
+
+./writeimg -nd ${LOOPDEV} ${BINFILE}
+./writeimg -vnd ${LOOPDEV} ${BINFILE}
+
+./writeimg -nd ${LOOPDEV} ./writeimg
+./writeimg -vnd ${LOOPDEV} ./writeimg
+
+./writeimg -nd ${LOOPDEV} ./LICENSE
+./writeimg -vnd ${LOOPDEV} ./LICENSE
+
+# Redirect this to avoid confusion
+! ./writeimg -vnd ${LOOPDEV} ./crc32.h 2>/dev/null
+
+GREEN="\e[32m"
+RESET="\e[0m"
+
+echo -e "\n\n${GREEN}Looks good!${RESET}"

writeimg.1

@@ -0,0 +1,38 @@
+.TH WRITEIMG 1 "February 2026" "writeimg" "User Commands"
+.SH NAME
+writeimg \- Write an image to a block device
+.SH SYNOPSIS
+.B writeimg
+\fB\-d\fR \fIDEVICE\fR \fIIMAGE\fR
+.br
+.B writeimg
+\fB\-\-device\fR \fIDEVICE\fR \fIIMAGE\fR
+
+.SH DESCRIPTION
+.B writeimg
+reads the input
+.I IMAGE
+and writes its contents to
+.I DEVICE
+
+The output device must be specified explicitly using the
+.B \-d
+or
+.B \-\-device
+option. The image file is given as a positional argument.
+.SH OPTIONS
+.TP
+.BR \-d ", " \-\-device" " DEVICE
+Device to write to.
+.TP
+.BR \-n ", " \-\-noconfirm
+Do not require confirmation from user.
+.TP
+.BR \-v ", " \-\-verify
+Verify only, do not write
+.SH EXAMPLES
+Write an image to a block device:
+.PP
+.nf
+    writeimg -d /dev/sdx file.img
+.fi

writeimg.c

@@ -3,6 +3,7 @@
 #include <fcntl.h>
 #include <getopt.h>
 #include <libgen.h>
+#include <limits.h>
 #include <signal.h>
 #include <stdint.h>
 #include <stdio.h>
@@ -41,8 +42,14 @@
 #define BAR_WIDTH 50
 
 void print_progress(int current, int total) {
-    float fraction = (float)current / total;
-    int   filled = (int)(fraction * BAR_WIDTH);
+    static int last = INT_MAX;
+    float      fraction = (float)current / total;
+    int        filled = (int)(fraction * BAR_WIDTH);
+
+    if (filled == last)
+        return; /* Avoid unnecessary io/flushes */
+
+    last = filled;
 
     printf("\r[");
     for (int i = 0; i < BAR_WIDTH; i++) {
@@ -65,7 +72,7 @@ const char help[] =
     "   -v                  Verify only\n"
     "   -d device           Target block device\n"
     "   -h, --help          Print this help message\n"
-    "   -n, --noconfirm     Do not ask for premission\n"
+    "   -n, --noconfirm     Do not ask for permission\n"
     "   -V, --version       Print version\n"
     "\0";
 // clang-format on
@@ -73,8 +80,8 @@ const char help[] =
 const char copyright[] = "Copyright (C) %s Imbus, BSD-2-Clause\n";
 
 struct write_job {
-    char  *filename;
-    char  *dev_name;
+    char  *iname;
+    char  *oname;
     char  *buffer;
     char  *buffer2; /* For memcmp integrity checks */
     size_t bufsize;
@@ -98,8 +105,8 @@ void int_handler(int signum) {
 }
 
 int perform_write(write_job_t *job) {
-    int block_fd = open(job->dev_name, O_RDWR);
-    int file_fd = open(job->filename, O_RDONLY);
+    int block_fd = open(job->oname, O_RDWR);
+    int file_fd = open(job->iname, O_RDONLY);
 
     assert(block_fd >= 0);
     assert(file_fd >= 0);
@@ -128,7 +135,7 @@ int perform_write(write_job_t *job) {
         }
 
         if (read_bytes < 0) {
-            fprintf(stderr, "%s: Read error\n", job->filename);
+            fprintf(stderr, "%s: Read error\n", job->iname);
             perror("Read");
             exit(EXIT_FAILURE);
         }
@@ -138,7 +145,7 @@ int perform_write(write_job_t *job) {
         if (job->flags & WI_WRITE) {
             ssize_t written_bytes = write(block_fd, job->buffer, read_bytes);
             if (written_bytes < 0) {
-                fprintf(stderr, "%s: Write error\n", job->dev_name);
+                fprintf(stderr, "%s: Write error\n", job->oname);
                 perror("Write");
                 exit(EXIT_FAILURE);
             }
@@ -219,13 +226,13 @@ int main(int argc, char *argv[]) {
             wjob.flags |= WI_VERIFY;
             wjob.flags &= ~WI_WRITE;
             continue;
-        case 'd': wjob.dev_name = optarg; continue;
+        case 'd': wjob.oname = optarg; continue;
         case 'h': break;
         case 'n': wjob.flags &= ~WI_ASK; continue;
         case 'V': exit(EXIT_SUCCESS);
         }
         printf("In honor of SwePwnage - the OG disk destroyer\n");
-        fprintf(stdout, copyright, CR_YEAR);
+        printf(copyright, CR_YEAR);
 #ifdef BLDDATE
         printf("Build date: %s\n", BLDDATE);
 #endif
@@ -244,39 +251,55 @@ int main(int argc, char *argv[]) {
         exit(EXIT_FAILURE);
     }
 
-    wjob.filename = argv[0];
+    wjob.iname = argv[0];
     struct stat file_stat = {0};
-    if (0 != stat(wjob.filename, &file_stat)) {
+    if (0 != stat(wjob.iname, &file_stat)) {
         printf("File does not exist...\n");
         exit(EXIT_FAILURE);
     }
 
-    if (NULL == wjob.dev_name) {
+    if (NULL == wjob.oname) {
         printf("You need to specify a device.\n");
         exit(EXIT_FAILURE);
     }
 
-    if (0 != strncmp(wjob.dev_name, "/dev/", 4)) {
-        printf("\"%s\" does not appear to be a block device...\n", wjob.dev_name);
+    if (0 != strncmp(wjob.oname, "/dev/", 4)) {
+        printf("\"%s\" does not appear to be a block device...\n", wjob.oname);
         exit(EXIT_FAILURE);
     }
 
-    /* Seems to be the cleanest way to check for write perm on a blockdev */
-    int fd = open(wjob.dev_name, O_WRONLY);
-    if (fd < 0) {
-        printf("Cannot write to \"%s\", do you have write permissions?\n", wjob.dev_name);
-        exit(1);
+    uint64_t device_size;
+    {
+        /* Seems to be the cleanest way to check for write perm on a blockdev */
+        int fd = open(wjob.oname, O_WRONLY);
+        if (fd < 0) {
+            printf("Cannot write to \"%s\", do you have write permissions?\n", wjob.oname);
+            close(fd);
+            exit(EXIT_FAILURE);
+        }
+
+#ifdef __GLIBC__
+        if (ioctl(fd, BLKGETSIZE64, &device_size) < 0) {
+#else /* With musl, ioctl's take ints, kheaders provide unsigned longs. Passes tests. */
+        if (ioctl(fd, (int)BLKGETSIZE64, &device_size) < 0) {
+#endif
+            perror("ioctl");
+            close(fd);
+            exit(EXIT_FAILURE);
+        }
+
+        close(fd);
     }
-    close(fd);
 
     wjob.total_bytes = file_stat.st_size;
     assert(file_stat.st_size >= 0);
 
     if (wjob.flags & WI_WRITE)
-        printf("Writing \"%s\" (%.1f MiB) to \"%s\"\n",
-               basename(wjob.filename),
+        printf("Writing \"%s\" (%.1f MiB) to \"%s\" (%.1f MiB)\n",
+               basename(wjob.iname),
                BYTES_TO_MIB(wjob.total_bytes),
-               wjob.dev_name);
+               wjob.oname,
+               BYTES_TO_MIB(device_size));
 
     if ((wjob.flags & WI_ASK) && (wjob.flags & WI_WRITE)) {
         printf("Is this okay? (y/N): ");

writeimg_completion_bash.sh

@@ -0,0 +1,25 @@
+_writeimg_completion() {
+    local cur prev opts
+
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+    opts="-v -d -h --help -n --noconfirm -V --version"
+
+    # Devices
+    if [[ "$prev" == "-d" ]]; then
+        COMPREPLY=( $(compgen -W "$(ls -d /dev/sd* /dev/nvme* /dev/mmcblk* 2>/dev/null)" -- "$cur") )
+        return 0
+    fi
+
+    # Flags
+    if [[ "$cur" != -* ]]; then
+        COMPREPLY=( $(compgen -f -- "$cur") )
+        return 0
+    fi
+
+    # Files
+    COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
+}
+
+complete -F _writeimg_completion writeimg