Skip to Content
gnux

basencx

Encode or decode data in one of several encodings.

Mirrors GNU basenc. Run it as basencx, or as gnux basencx.

Synopsis

basencx [OPTION]... [FILE]

GNU reference

Description

basencx encodes FILE in the encoding an option selects and writes the result to standard output, or with -d decodes it. With no FILE, or when FILE is -, it reads standard input; at most one FILE is accepted. An encoding must be given: --base64 and --base32 are base64x and base32x; --base64url is base64 with '-' and '_' in place of '+' and '/', safe in file names and URLs; --base32hex is base32 over 0-9 and A-V; --base16 is upper-case hexadecimal (decoding takes either case); --base2msbf and --base2lsbf write every byte as eight '0' and '1' characters, most or least significant bit first; --z85 is ZeroMQ's Z85, which turns each four bytes into five characters and refuses input that is not a whole number of groups. If several are given, the last one wins. Encoded output is wrapped every 76 characters and ends with a newline; -w COLS wraps at COLS instead, and -w 0 writes one line with no newline at all. When decoding, newlines are ignored and -i also ignores every other character outside the alphabet; any other stray character, or a truncated input, stops decoding with 'invalid input' and exit status 1, after the data decoded so far has been written.

Permissions

Needs read permission on FILE and search permission on the directories leading to it. Nothing is ever modified.

Use cases

  • Making tokens and identifiers safe for URLs and file names with --base64url.
  • Writing a hex dump of a key or digest with --base16.
  • Looking at the bits of a byte string with --base2msbf.
  • Decoding Z85 strings used by ZeroMQ, such as CURVE keys.

Flags

      --base16           hex encoding (RFC4648 section 8)
      --base2lsbf        bit string with least significant bit (lsb) first
      --base2msbf        bit string with most significant bit (msb) first
      --base32           same as 'base32' program (RFC4648 section 6)
      --base32hex        extended hex alphabet base32 (RFC4648 section 7)
      --base64           same as 'base64' program (RFC4648 section 4)
      --base64url        file- and url-safe base64 (RFC4648 section 5)
  -d, --decode           decode data
      --help             display this help and exit
  -i, --ignore-garbage   when decoding, ignore non-alphabet characters
      --version          output version information and exit
  -w, --wrap COLS        wrap encoded lines after COLS character (default 76); use 0 to disable line wrapping
      --z85              ascii85-like encoding (ZeroMQ spec:32/Z85); when encoding, input length must be a multiple of 4; when decoding, input length must be a multiple of 5

Examples

Encode a value for a URL, where '+' and '/' would need escaping

printfx '>>?' | basencx --base64url
Output
Pj4_
basencx --base16 -w 0 key.bin

Turn a hex string back into bytes

echox 68656c6c6f | basencx --base16 -d
Output
hello

See the bits of a character

printfx A | basencx --base2msbf
Output
01000001

Decode a ZeroMQ CURVE key written in Z85

printfx '%s' "$KEY" | basencx --z85 -d > key.bin

Encode in base32 with the hex alphabet, which sorts as the data does

printfx hello | basencx --base32hex
Output
D1IMOR3F

Options

Each option has a page of its own, with its usage and examples.

  • --base16: Hex encoding (RFC4648 section 8).
  • --base2lsbf: Bit string with least significant bit (lsb) first.
  • --base2msbf: Bit string with most significant bit (msb) first.
  • --base32: Same as 'base32' program (RFC4648 section 6).
  • --base32hex: Extended hex alphabet base32 (RFC4648 section 7).
  • --base64: Same as 'base64' program (RFC4648 section 4).
  • --base64url: File- and url-safe base64 (RFC4648 section 5).
  • -d, --decode: Decode data.
  • -i, --ignore-garbage: When decoding, ignore non-alphabet characters.
  • -w, --wrap: Wrap encoded lines after COLS character (default 76); use 0 to disable line wrapping.
  • --z85: Ascii85-like encoding (ZeroMQ spec:32/Z85); when encoding, input length must be a multiple of 4; when decoding, input length must be a multiple of 5.

Exit status

StatusMeaning
0success: every operand was processed
1failure: an operand could not be processed (diagnosed on standard error), or a command-line mistake

Help in the terminal

basencx --help                # options, first examples, exit status
gnux help basencx             # this page: the full manual
gnux help basencx --OPTION    # one option in depth, with its examples

See also

On this page