//po4a: entry man manual
////

SPDX-License-Identifier: GPL-2.0-or-later

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

Copyright (c) 2024 Robin Jarry

////
ifdef::neverdefined[---]

= bits(1)
:doctype: manpage
:man manual: User Commands
:man source: util-linux {release-version}
:page-layout: base
:command: bits

== NAME

bits - convert bit masks or lists from/to various formats

== SYNOPSIS

*bits* [*-h*] [*-V*] [*-w* _number_] [_mode_] [_mask_|_list_]...

== DESCRIPTION

The *bits* utility converts between bit masks and bit lists.
It supports combining multiple masks or lists using bitwise operations.

== POSITIONAL ARGUMENTS

_mask_::
A set of bits specified as a hexadecimal mask value
(for example: *0xeec2*).
_list_::
A set of bits specified as a comma-separated list of bit IDs
(for example: *1,5,29,32*).

If no argument is specified, the sets of bits will be read from
standard input, one group per line.

Consecutive IDs can be compressed as ranges
(for example: *5,6,7,8,9,10* -> *5-10*).

Optionally, if an argument starts with a comma, it will be
parsed as a single hexadecimal mask split in 32-bit groups
(for example: *,00014000,00000000,00020000* -> *17,78,80*).

By default, all groups will be OR'ed together. If a group has one of
the prefixes **&**, **^**, or **~**, it will be combined with the
resulting mask using a different binary operation:

**&**__mask__|**&**__list__::
The group will be combined with a binary AND operation.
That is: all bits that are set to 1 in the group AND in the combined groups
so far will be preserved as 1. All other bits will be reset to 0.

**^**__mask__|**+++^+++**__list__::
The group will be combined with a binary XOR operation.
That is: all bits that are set to 1 in the group AND to 0 in the combined
groups so far (or the other way around) will be set to 1.
Bits that are set both to 1 or both to 0 will be reset to 0.

**~**__mask__|**+++~+++**__list__::
All bits set to 1 in the group will be cleared (reset to 0) in the combined
groups so far.

== OPTIONS

*-w* _number_, *--width* _number_::
The maximum number of bits in the masks handled by *bits*.
The default is *8192*. Any bit larger than this number will be truncated.

include::man-common/help-version.adoc[]

== CONVERSION MODE

One of the following conversion modes can be specified. If not specified, it
defaults to *-m*, *--mask*.

*-b*, *--binary*::
Print the combined arguments as a binary mask value.

*-g*, *--grouped-mask*::
Print the combined arguments as a hexadecimal mask value
in 32-bit comma-separated groups.

*-l*, *--list*::
Print the combined arguments as a list of bit IDs.
Consecutive IDs are compressed to ranges.

*-m*, *--mask*::
Print the combined arguments as a hexadecimal mask value (default).

== EXAMPLES

....
~$ bits --mask 4,5-8 16,30
0x400101f0

~$ bits --list 0xeec2
1,6,7,9-11,13-15

~$ bits --binary 4,5-8 16,30
0b100_0000_0000_0001_0000_0001_1111_0000

~$ bits --list ,00300000,03000000,30000003
0,1,28,29,56,57,84,85

~$ bits --list 1,2,3,4 ~3-10
1,2

~$ bits --list 1,2,3,4 ^3-10
1,2,5-10

~$ bits --grouped-mask 2,22,74,79
8400,00000000,00400004

~$ bits --width 64 --list 2,22,74,79
2,22
....

== AUTHORS

Robin Jarry.

include::man-common/bugreports.adoc[]

include::man-common/footer.adoc[]

ifdef::translation[]
include::man-common/translation.adoc[]
endif::[]
