By Pudge

We are based on Arch which uses Pacman as the package manager and it comes with a man.. as in the manual page. But what exactly is it? Well, here’s what the man page says about the man page.

To access the man pages, the dreaded Command Line Interface must be used, so open a terminal window and enter:

$ man man

MAN(1) Manual pager utils MAN(1) NAME man – an interface to the system reference manuals SYNOPSIS man

DESCRIPTION

man is the system’s manual pager. Each page argument given to man is normally the name of a program, utility or function.

The manual page associated with each of these arguments is then found and displayed. A section, if provided, will direct man to look only in that section of the manual. The default action is to search in all of the available sections following a pre-defined order (see DEFAULTS) and to show only the first page found, even if the page exists in several sections.

Every man page should follow a prescribed format. NAME, SYNOPSIS, and DESCRIPTION should always be first. These should be self-explanatory. Notice in the SYNOPSIS the line:

man -k [apropos options] regexp

Parsing the command gives

“man” invokes the man command

“-k” specifies to use the apropos option

[apropos options] anything in brackets is optional, in this case, options for apropos may be specified. If no options are specified, don’t include the empty brackets “regexp” is the target that man operates on, in this case, the target is the regexp command.

I chose this particular line to parse since apropos was covered in “Linux commands demystified Part one”. If you need to see the options available for apropos, then enter

$ man apropos

The man pages are very flexible in how it displays things. Most of the time, a simple

$ man regexp

would yield results that would be satisfactory. If not, then explore some of the display options.

The first page of the man command is displayed above. Here is how to navigate in the man pages.

By default, man redirects the output through less command. To navigate in the less output, up and down arrows move the text up and down one line at a time. The space bar moves text forward one page, b moves the text backwards one page. h displays movement options for less. q exits the less command. For further info on less, do a

$ man less

Scroll down until the following appears

The table below shows the section numbers of the manual followed by the types of pages they contain. 1 Executable programs or shell commands 2 System calls (functions provided by the kernel) 3 Library calls (functions within program libraries) 4 Special files (usually found in /dev) 5 File formats and conventions, e.g. /etc/passwd 6 Games 7 Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7) 8 System administration commands (usually only for root) 9 Kernel routines [Non-standard] A manual page consists of several sections. Conventional section names include NAME, SYNOPSIS, CONFIGURATION, DESCRIPTION, OPTIONS, EXIT STATUS, RETURN VALUE, ERRORS, ENVIRONMENT, FILES, VERSIONS, CONFORMING TO, NOTES, BUGS, EXAMPLE, AUTHORS, and SEE ALSO.

As stated above in the DESCRIPTION

The manual page associated with each of these arguments is then found and displayed. A section, if provided, will direct man to look only in that section of the manual.

How is this useful? In the SEE ALSO section, you will often be referred to other man pages such as pacman.conf(5) This will display section 5 of the pacman.conf man page, thus limiting the size of the displayed man page. In this case section 5 is File formats and conventions. Enter as:

$ man pacman.conf 5

Now we can open a man page, and navigate around in the man page. At this point, you are probably saying to yourself, “Man, that is just a bunch of gobbledygook. Why do I need this?” Quite often when asking for help on a Linux forum, or while reading Linux Blogs, someone will throw a CLI command at you. You may or may not understand what the command does or what the options mean.

Rather than blindly typing in the command and hoping for the best, you can research the command with the man pages.

We will start by examining the most used CLI command, pacman. Everyone using EndeavourOS has seen pacman -S packagename and pacman -Syu

Open the man page for pacman and we’ll dissect these commands.

$ man pacman

PACMAN(8) Pacman Manual PACMAN(8) NAME pacman – package manager utility SYNOPSIS pacman <operation> [options] [targets] DESCRIPTION Pacman is a package management utility that tracks installed packages on a Linux system. It features dependency support, package groups, install and uninstall scripts, and the ability to sync your local machine with a remote repository to automatically upgrade packages. Pacman packages are a zipped tar format. Since version 3.0.0, pacman has been the front-end to libalpm(3), the “Arch Linux Package Management” library. This library allows alternative front-ends to be written (for instance, a GUI front-end). Invoking pacman involves specifying an operation with any potential options and targets to operate on. A target is usually a package name, file name, URL, or a search string. Targets can be provided as command-line arguments. Additionally, if stdin is not from a terminal and a single hyphen (-) is passed as an argument, targets will be read from stdin.

From above, “Invoking pacman involves specifying an operation with any potential options and targets to operate on.” For:

pacman -S package-name

-S is the operation, there are no options, and the package name is the target. -S with no options will synchronize packages and install the target package name. The -S operation is defined as:

OPERATIONS -S, --sync Synchronize packages. Packages are installed directly from the remote repositories, including all dependencies required to run the packages. For example, pacman -S qt will download and install qt and all the packages it depends on. If a package name exists in more than one repository, the repository can be explicitly specified to clarify the package to install: pacman -S testing/qt. You can also specify version requirements: pacman -S "bash>=3.2". Quotes are needed, otherwise, the shell interprets “>” as redirection to a file.

The above is a snippet, see man pacman for further details on the -S operation.

On to pacman -Syu. The -S operation has been examined, time to check out the options. For:

pacman -Syu

-S is the operation, y and u are the options, and there is no target. Scroll down to the

SYNC OPTIONS (APPLY TO -S)

section to find the option definitions.

-y, --refresh Download a fresh copy of the master package database from the server(s) defined in pacman.conf(5). This should typically be used each time you use –sysupgrade or -u. Passing two –refresh or -y flags will force a refresh of all package databases, even if they appear to be up-to-date.

-y downloads a fresh copy of the master package database from the server(s)

This should typically be used each time you use –sysupgrade or -u

-yy will force a refresh of all package databases, even if they appear to be up to date.

I’ve seen the -yy option used to repair a local package database that has become corrupt.

-u, --sysupgrade Upgrades all packages that are out-of-date. Each currently-installed package will be examined and upgraded if a newer package exists. A report of all packages to upgrade will be presented, and the operation will not proceed without user confirmation. Dependencies are automatically resolved at this level and will be installed/upgraded if necessary. Pass this option twice to enable package downgrades; in this case, pacman will select sync packages whose versions do not match with the local versions. This can be useful when the user switches from a testing repository to a stable one. Additional targets can also be specified manually, so that -Su foo will do a system upgrade and install/upgrade the “foo” package in the same operation.

-u upgrades all packages that are out of date.

-uu will enable package downgrades. This would probably rarely be used. See the wiki entries about downgrading to a specific date.

Since the -u option was specified, there is no target.

pacman -S -y -u

pacman -Syu

pacman -S - -sysupgrade - -refresh

Are all equivalent and will run just fine. pacman -Syu is just easier to type.

A few useful pacman commands using -Q (query) and we will wrap this up.

-Q, --query Query the package database. This operation allows you to view installed packages and their files, as well as meta-information about individual packages (dependencies, conflicts, install date, build date, size). This can be run against the local package database or can be used on individual package files. In the first case, if no package names are provided in the command line, all installed packages will be queried. Additionally, various filters can be applied on the package list. See Query Options below.

pacman -Q

If no package names are provided in the command line, all installed packages will be queried. This will provide a list of ALL packages installed. Most of the time this is not real useful. However, during troubleshooting if someone on a forum asks if you have a certain package installed, you can do the following;

pacman -Q | grep packagename

or just part of package name. Such as

pacman -Q | grep xf86-video

xf86-video-amdgpu 19.1.0-1

xf86-video-ati 1:19.1.0-1

xf86-video-fbdev 0.5.0-1

xf86-video-intel 1:2.99.917+897+g0867eea6-1

xf86-video-vesa 2.4.0-2

Yields anything that starts with xf86-video Which is the above on my EndeavourOS Gnome system.


To parse this command:

pacman is the command, -Q is the operation, no options, and no target, will list all installed packages.

This output is “piped” or sent to the grep command which limits the output to anything starting with xf86-video. Might be a good time to do a man grep. Also, the “pipe” command is the two vertical dashes that are the shifted \ (backslash) key on a US keyboard layout.

Over time, orphan or ghost packages will start to accumulate. To find them:

pacman -Qdt

-d, –deps Restrict or filter output to packages installed as dependencies. This option can be combined with -t for listing real orphans – packages that were installed as dependencies but are no longer required by any installed package.

The -d option restricts the query output to packages installed as dependencies. Sure enough, “This option can be combined with -t for listing real orphans.”

-t, --unrequired Restrict or filter output to print only packages neither required nor optionally required by any currently installed package. Specify this option twice to include packages which are optionally, but not directly, required by another package.

-t Restrict or filter output to print only packages neither required nor optionally required by any currently installed package.

-tt Specify this option twice to include packages which are optionally, but not directly, required by another package.

We want the -t option. Packages not required by any package, in any way.

If some orphans were found, how to eliminate them? As per the Arch Wiki**, use:

pacman -Rns $(pacman -Qtdq)

In the (pacman -Qtdq) part, everthing has been covered this far exept the q option.

-q, –quiet Show less information for certain query operations. This is useful when Pacman’s output is processed in a script. Search will only show package names and not a version, group, and description information; own will only show package names instead of “file is owned by pkg” messages; group will only show package names and omit group names; list will only show files and omit package names; check will only show pairs of package names and missing files; a bare query will only show package names rather than names and versions.

This should be self-explanatory. Now about the first part of the command.

pacman -Rns $(pacman -Qtdq)

The OPERATION is

-R, –remove Remove package(s) from the system. Groups can also be specified to be removed, in which case every package in that group will be removed. Files belonging to the specified package will be deleted and the database will be updated. Most configuration files will be saved with a .pacsave extension unless the –nosave option is used. See Remove Options below.

This removes packages from the system.

Scroll to

REMOVE OPTIONS (APPLY TO -R)

-n, –nosave Instructs pacman to ignore file backup designations. Normally, when a file is removed from the system, the database is checked to see if the file should be renamed with a .pacsave extension.

-s, –recursive Remove each target specified including all of their dependencies, provided that (A) they are not required by other packages; and (B) they were not explicitly installed by the user. This operation is recursive and analogous to a backwards –sync operation, and it helps keep a clean system without orphans. If you want to omit condition (B), pass this option twice.

$(COMMAND) is shorthand for substitute the output of the enclosed command
To parse the command.
pacman -Rns $(pacman -Qtdq)
run pacman with -Rns which recursively removes target files without saving config files, and use the output of  the $(pacman -Qtdq) command as the targets.  

That last command sure warped my brain.  Time to shut this party down.

I want to give a shout out to EndeavourOS forum member CMarch for his assistance with this article.

A big thank you to bryanpwo for everything Bryan did to get this edited and formatted for the Discovery magazine.  

** Cited reference from the Arch Wiki
https://wiki.archlinux.org/index.php/Pacman/Tips_and_tricks#Removing_unused_packages_(orphans)

To give credit where credit is due for the pacman man page, scroll to the very bottom of the man page to AUTHORS

Since pacman was written from scratch by Judd Vinet, I am reasonably sure Judd wrote the original man page for his creation.  His name is listed under "Past major contributors".  Thank you to Judd and all the current maintainers and past major contributors to this man page, and to everyone who keeps Arch Linux what it is today.