qatom

Section: qatom (1)
Updated: Feb 2026
Index Return to Main Contents

---

 

NAME

qatom - split atom strings  

SYNOPSIS

qatom [opts] <pkg>  

DESCRIPTION

qatom parses strings into atoms and optionally compares them. The parsing into atoms results in CATEGORY, PN (package name), PV (package version), PR (package revision), SLOT and REPO. Next to these version qualifiers (e.g. >, <, or =) and optional * suffix are extracted. All but PN are optional.

Comparison of atoms returns the relationship between two parsed atoms. qatom does not allow to test conditions. It is possible to perform multiple comparisons by simply adding more arguments. Comparisons are, however, always performed two by two, so there must be an even count of arguments to the compare function.

The qatom applet is a direct wrapper around the atom parsing functionalities used by various other applets. As such this applet allows easy testing or atom parsing and comparison behaviour.  

OPTIONS

-F <arg>, --format <arg>

Specify a custom output format. The default format is

%{CATEGORY} %{PN} %{PV} %[PR] %[SLOT] %[pfx] %[sfx]

Conversion specifiers start with a % symbol and are followed by either { or [. Next is the name of the field to expand, followed by a matching } or ]. The difference between { and [ is that the latter is only printed if the field referred is set, while the former prints <unset> in that case.

The following fields are supported, which are inline with the variables from ebuild(5).

CATEGORY

The category of the package.

P

The package name and version without the ebuild revision.

PN

The package name.

PV

The package version without the ebuild revision.

PVR

The package version including ebuild revision, which is also printed when zero, unlike for PF.

PF

The package name, version and revision when not zero. Thus, a zero revision -r0 is not printed.

PR

The ebuild revision, when force printed, outputs -r0 when unset.

SLOT

The package slot, when force printed, outputs - when unset.

REPO

The package repository.

pfx

The package prefixes, that is version specifiers.

sfx

The package suffices, currently that is just the asterisk.

-c, --compare

Compare two atoms.

-s, --scompare

Compare two atoms in the given order data, query.

-p, --print

Print reconstructed atom.

-l, --lookup

Lookup atom in tree.

--root <arg>

Set the ROOT env var.

-v, --verbose

Force all expansions, basically treat all [ like {.

-q, --quiet

Ignored for compatibility with other qapplets.

-C, --nocolor

Ignored for compatibility with other qapplets.

--color

Force color in output.

-h, --help

Print this help and exit.

-V, --version

Print version and exit.

 

ANTISLOT

A feature present in portag-utils is the s-called antislot, and is activated by starting the atom with a carrot (^), in place of the blocker bang (!). The antislot is similar to the inversing behaviour of a blocker, but only operates on SLOT and SUBSLOT, and requires SLOT to be available, e.g. it won't match unset SLOT (NULL).

The antislot is mostly useful with dependencies and is best described with an example. Consider a perl upgrade from perl:0/5.28 to perl:0/5.30. To find a consumer for perl:0/5.28 a simple match can be made, e.g. using qdependsRf(1):

        $ qdepends-Q perl:0/5.28
        virtual/per-ExtUtil-MakeMake-7.340.-r1: ... de-lang/perl:0/5.28 ...
        ...

However, to query after perl:0/5.30 is installed, which packages are still not rebuilt (e.g. depending on an older perl: 5.28, 5.26, etc.) one can use the antislot:

        $ qdepends-Q ^perl:0/5.30
        ...

This will return any package that depends on perl:0 not having subslot 5.30. Obviously this can be tested using qatom using the -c option:

        $ qatom-c ^perl:0/5.30 per-5.28.1:0/5.28
        ^perl:0/5.30 == per-5.28.1:0/5.28

 

REPORTING BUGS

Please report bugs via http://bugs.gentoo.org/
Product: Gentoo Linux; Component: Current packages  

AUTHORS

Ned Ludd <solar@gentoo.org>
Mike Frysinger <vapier@gentoo.org>
Fabian Groffen <grobian@gentoo.org>

 

SEE ALSO

q(1), qcheck(1), qdepends(1), qfile(1), qgrep(1), qkeyword(1), qlist(1), qlop(1), qmanifest(1), qmerge(1), qpkg(1), qsearch(1), qsize(1), qtbz2(1), qtegrity(1), quse(1), qwhich(1), qxpak(1)

---

 

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

ANTISLOT

REPORTING BUGS

AUTHORS

SEE ALSO