--- /dev/null
+# AGENTS.md
+
+This file provides guidance to AI coding agents working on this repository.
+
+util-linux is a collection of essential Linux system utilities and libraries
+(libmount, libblkid, libsmartcols, libfdisk, libuuid). The project follows
+Linux kernel coding conventions and workflows.
+
+## Legal
+
+Only human beings can be credited in commit messages. Do not include
+Co-Developed-By, Co-Authored-By, or similar attribution for AI models.
+Commits should include a Signed-off-by line (`git commit -s`).
+
+## Key Documentation
+
+Always consult these files as needed:
+
+- `Documentation/HOWTO-BUILDING.md` — how to compile the project, build system internals
+- `Documentation/HOWTO-CONTRIBUTING.md` — contribution guidelines, patch and PR workflow
+- `Documentation/HOWTO-HACKING.md` — coding details: usage functions, man pages, debugging
+- `Documentation/HOWTO-TESTING.md` — regression test framework, environment variables
+
+## Code Style
+
+The coding style is based on the Linux kernel coding style.
+
+- Do NOT use `{ }` braces for single-line if/else blocks.
+- Do not use `else` after non-returning functions (err(), errx(), exit(), ...).
+- Avoid `if ((rc = func()) != 0)` — split into separate assignment and comparison:
+ ```c
+ rc = func();
+ if (rc != 0)
+ ```
+- Use `printf()` consistently, not `fprintf(stdout, ...)`.
+- Follow existing naming and coding conventions in each file.
+- Use EditorConfig (`.editorconfig` in the project root) for whitespace settings.
+
+## Function Return Conventions
+
+- Boolean functions return true/false — name with `_is_`, `_has_`, `_can_`.
+- Iterator `_next_` functions: 0 = success, <0 = error, 1 = end of list.
+- Error-returning functions: negative errno or NULL.
+- Check existing similar functions in libsmartcols, libmount for API consistency.
+
+## Memory Management
+
+- For non-library code, use `include/xalloc.h` wrappers (`xmalloc()`, `xcalloc()`,
+ `xstrdup()`, etc.) — these always succeed or terminate with `err()`.
+- In libraries, check ownership semantics: does the function take ownership or copy?
+- Trace every `malloc`/`calloc`/`strdup`/`asprintf` to its corresponding `free()`.
+- `list_del()` must also free the element memory, not just unlink.
+- Watch for missing `free()` on error/early-return paths.
+
+## Commit Messages
+
+- Use `Fixes:` when the commit resolves an issue.
+- Use `Addresses:` when the commit only partly implements requested changes.
+- Always use complete GitHub URLs, for example:
+ `Fixes: https://github.com/util-linux/util-linux/issues/NNN`
+- Do not commit generated files (po/, po-man/, ./configure, ...).
+
+## Build and Test
+
+The project supports two build systems: autotools and meson.
+
+Autotools:
+
+- Build: `./autogen.sh && ./configure && make`
+- Run tests: `make check` or `cd tests && ./run.sh`
+- Selective build: `./configure --disable-all-programs --enable-<name>`
+
+Meson:
+
+- Build: `meson setup build && meson compile -C build`
+- Run tests: `meson test -C build`
+
+Features should include corresponding tests.
--- /dev/null
+# About Documentation
+
+The util-linux Documentation/ directory contains supplementary material
+such as readme files, release notes, and licenses. These files contain
+information for contributors and should not end up in end-user installations.
+
+## Key Documents
+
+- [HOWTO-BUILDING.md](HOWTO-BUILDING.md) — how to compile the project, build system internals
+- [HOWTO-CONTRIBUTING.md](HOWTO-CONTRIBUTING.md) — contribution guidelines, patch and PR workflow
+- [HOWTO-HACKING.md](HOWTO-HACKING.md) — coding details: usage functions, man pages, debugging
+- [HOWTO-TESTING.md](HOWTO-TESTING.md) — regression test framework, environment variables
+++ /dev/null
-What is here
-------------
-
-The util-linux contains supplementary textual material, such as
-readme files, release notes, licenses and so on. Common to these
-files is that they contain information for contributors but
-should not end up to end user installation.
--- /dev/null
+# Building util-linux
+
+## Quick Start
+
+Autotools:
+
+ ./autogen.sh && ./configure && make
+
+If something fails, check the last lines — the typical reason is a missing
+dependency such as libtool or gettext.
+
+Meson:
+
+ meson setup build
+ meson compile -C build
+
+## Autotools Basics
+
+- `./autogen.sh` generates all files needed to compile (run after git checkout)
+- `make distclean` removes generated files; code can still be recompiled
+ with `./configure && make`
+- `make dist-gzip` (or `-bzip2`) creates a tarball that works without `./autogen.sh`
+
+## Selective Compilation
+
+See `./configure --help` for `--disable-*` and `--enable-*` options.
+
+Build only specific programs:
+
+ ./configure --disable-all-programs --enable-fallocate
+
+The configure script tracks dependencies between libs and tools. Follow
+warning/error messages. For example, mount(8) needs libmount, libblkid
+and libuuid:
+
+ ./configure --disable-all-programs --enable-mount \
+ --enable-libmount --enable-libblkid --enable-libuuid
+
+## Compiler Flags
+
+Use `SUID_CFLAGS` and `SUID_LDFLAGS` for suid programs (chfn, chsh,
+newgrp, su, write, mount, umount):
+
+ ./configure SUID_CFLAGS="-fpie" SUID_LDFLAGS="-pie"
+
+Use `DAEMON_CFLAGS` and `DAEMON_LDFLAGS` for daemons (uuidd).
+
+Use `SOLIB_CFLAGS` and `SOLIB_LDFLAGS` for shared libraries (libmount,
+libblkid, libuuid).
+
+## Static Linking
+
+Use `--enable-static-programs[=LIST]`.
+
+Note that mount(8) uses NSS functions (get{pw,gr}nam, getpwuid) which may
+be dynamically loaded even in static builds. The UID/GID translation will
+not work in environments where NSS modules are not installed.
+
+## Build System Internals
+
+The autotools build system is non-recursive — subdirectories use `Makemodule.am`
+files that are merged by automake into one global Makefile.
+
+- All build results (binaries, libtool scripts) go in the top-level directory
+- `Makemodule.am` files must use full paths (e.g., `foo_SOURCES = subdir/foo.c`)
+- Always use `+=` for global variables (e.g., `bin_PROGRAMS += foo`)
+- Use `libcommon.la` (without path) for lib/ stuff
+- For libblkid/libuuid/libmount use `lib<name>.la` in `_LDADD` and
+ `-I$(ul_lib<name>_incdir)` in `_CFLAGS`
+- Always use suffixes for hooks (e.g., `install-exec-hook-foo`)
+- All autoconf macros use the `UL_` prefix
+- Utils are enabled/disabled via `BUILD_<NAME>` conditions (`AM_CONDITIONAL`)
+- `BUILD_<NAME>` blocks are never nested; dependencies are resolved in `configure.ac`
+ (see `UL_REQUIRES_BUILD()`)
+
+Predefined configure scenarios are in `tools/config-gen.d/`:
+
+ ./tools/config-gen all selinux
+
+WARNING: `config-gen` is for development only, not for end-user or
+downstream distribution builds.
--- /dev/null
+# Contributing to util-linux
+
+## Repositories & Branches
+
+Primary repository:
+
+ git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
+
+GitHub (backup, pull requests, issue tracking):
+
+ git clone https://github.com/util-linux/util-linux.git
+
+It's recommended to use github.com for development.
+
+Branches:
+
+- `master` — continuous development, never feature-frozen
+- `stable/vX.Y` — stable releases, branched from master
+
+Since version 2.40, stabilization is done exclusively in `stable/` branches.
+
+## Sending Patches
+
+- Send patches via GitHub pull request (recommended) or to the mailing
+ list (see README).
+- One patch per commit, many small patches preferred over a single large one.
+ Split by logical functionality.
+- Do not include generated files (autotools, po/, po-man/).
+- Do not include po/ translation changes — translations are maintained at
+ https://translationproject.org/domain/util-linux.html
+- Patches must be distribution-neutral (no RPMs, DEBs, etc.).
+- Alternatively, use `git format-patch` and `git send-email` to submit
+ patches to the mailing list (see README).
+
+## Commit Messages
+
+- Subject: `subsystem: description`
+- Add a Signed-off-by line (`git commit -s`).
+- Use `Fixes:` when the commit resolves an issue.
+- Use `Addresses:` when the commit only partly implements requested changes.
+- Always use complete GitHub URLs:
+ `Fixes: https://github.com/util-linux/util-linux/issues/NNN`
+
+## Pull Request Workflow
+
+1. Fork the repository on GitHub.
+
+2. Create a branch for your work (do not use `master` for contributions):
+
+ git checkout master
+ git branch my-feature
+ git checkout my-feature
+
+3. Keep your branch up to date by rebasing on master:
+
+ git fetch --all
+ git checkout master
+ git merge origin/master
+ git checkout my-feature
+ git rebase master
+
+4. Push and create a pull request:
+
+ git push yourgit my-feature
+
+5. When resubmitting after review, incorporate reviewer comments and
+ force-push the updated branch:
+
+ git rebase -i master
+ # fix things
+ git push -f yourgit my-feature
+
+6. After your branch is merged or rejected, clean up:
+
+ git branch -d my-feature
+ git push yourgit :my-feature
+
+## Patching Process
+
+- Make sure the code compiles without errors or warnings.
+- Test that existing behavior is not altered. If behavior changes
+ intentionally, explain what and why in the commit message.
+- Only submit changes you believe are ready to merge. For review-only
+ patches, mark them as RFC.
+- Incorporate reviewer comments before resubmitting.
+
+## Coding Style
+
+The preferred coding style is based on the Linux kernel coding style:
+https://docs.kernel.org/process/coding-style.html
+
+- Use `FIXME:` with a description for known issues you are not fixing
+ in the current change.
+- Do not use `else` after non-returning functions.
+- When short if-else wraps to multiple lines, use the full `if () { } else { }` syntax.
+- Consider installing an EditorConfig plugin (https://editorconfig.org/).
+
+## Options
+
+- Once options exist, they must not be changed, removed, or have their
+ behavior altered.
+- `-h, --help` and `-V, --version` are reserved.
+- Do not introduce new single-dash long options or non-standard option
+ characters.
+
+## Standards Compliance
+
+Some commands have Open Group / POSIX requirements: cal, col, ipcrm,
+ipcs, kill, line, logger, mesg, more, newgrp, pg, renice.
+
+When modifying these, do not conflict with the latest standard. New short
+options should not be added before they are part of the standard;
+new long options are acceptable.
+
+## Various Notes
+
+- util-linux does not use kernel headers for filesystem super block structures.
+- Patches relying on kernel features not in Linus Torvalds's tree are not accepted.
--- /dev/null
+# Hacking on util-linux
+
+## Man Pages
+
+Since v2.37 util-linux uses asciidoc format for man pages.
+See `man-common/manpage-stub.adoc` for details.
+
+## Usage Function
+
+Refer to `Documentation/boilerplate.c` for a complete example.
+
+### Format
+
+The `usage()` output consists of: Usage section, one-line command description,
+Options section, optional special sections (e.g., 'Available columns'), and
+a final man page reference line. Each section is separated by one empty line.
+
+Only the synopsis and option lines are indented (one space).
+Option lines do not use line-ending punctuation.
+
+### Synopsis
+
+Diamond brackets `<arg>` mark required arguments, square brackets `[arg]`
+mark optional ones. Optional option arguments require `=` with no whitespace:
+`--optional[=<arg>]`. Three dots `...` indicate unlimited repetition.
+
+Use multiple synopsis lines when a command does fundamentally different things
+depending on options/arguments:
+
+ ionice [options] -p <pid> ...
+ ionice [options] <command> [<arg> ...]
+
+### Option Descriptions
+
+- Short option first, then long option, separated by comma and space.
+- Description starts at the column of the longest option plus two spaces.
+- Maximum width is 80 characters; use indented continuation lines if needed.
+- `--help` and `--version` are always last.
+- One gettext entry per option — be nice to translators.
+
+Use the `USAGE_HELP_OPTIONS(<num>)` macro from `include/c.h` for the
+help/version options, where `<num>` is the description start column.
+
+### Usage Function Rules
+
+- `usage()` never returns — it is only called by `-h`/`--help`.
+- All other error cases use `errtryhelp(EXIT_FAILURE)`.
+- Use string constants from `include/c.h` for section headers.
+
+## Debugging
+
+### Libtool Wrappers (autotools only)
+
+Binaries built with autotools/libtool are wrapped by shell scripts. The
+actual binary is in `.libs/` (e.g., `mount/.libs/mount`). To run it
+directly with gdb or valgrind, set `LD_LIBRARY_PATH`:
+
+ export LD_LIBRARY_PATH=$PWD/libblkid/src/.libs/:$LD_LIBRARY_PATH
+
+Meson builds produce directly usable binaries without wrappers, so this
+is not needed when building with meson.
+
+### Library Debug Output
+
+All libraries support debug output via environment variables:
+
+ export LIBBLKID_DEBUG=all
+ export LIBMOUNT_DEBUG=all
+ export LIBFDISK_DEBUG=all
+ export LIBSMARTCOLS_DEBUG=all
+
+See `libblkid/src/blkidP.h` and `libmount/src/mountP.h` for the meaning
+of individual debug flags.
+
+### Libmount Path Overrides
+
+These environment variables override default paths (ignored for non-root):
+
+| Variable | Default |
+|---|---|
+| `LIBMOUNT_FSTAB` | `/etc/fstab` |
+| `LIBMOUNT_MTAB` | `/etc/mtab` |
+| `LIBMOUNT_UTAB` | `/run/mount/utab` |
+
+### Libblkid Overrides
+
+- `BLKID_CONF` — override `/etc/blkid.conf`
+- `BLKID_FILE` — override cache file location (see blkid(8))
--- /dev/null
+# Testing util-linux
+
+## Quick Start
+
+Compile and run basic tests:
+
+ make check
+
+Or with meson:
+
+ meson test -C build
+
+Run all tests including those requiring root:
+
+ # cd tests
+ # ./run.sh [options, see --help]
+
+Or using sudo with make:
+
+ $ make check-programs
+ $ sudo -E make check TS_OPTS="--parallel=1"
+
+Note: as root you must manually remove output and diff directories
+(`rm -rf output diff`) or run `make clean` as root.
+
+Note: the configure option `--disable-static` disables many libmount
+and libblkid unit tests.
+
+## Running Specific Tests
+
+Run a test group:
+
+ $ cd tests
+ $ ./run.sh blkid
+ $ ./run.sh libmount
+
+Run an individual test:
+
+ $ ./ts/cal/year
+
+Exclude tests:
+
+ $ ./run.sh --exclude="mount/move"
+
+## Compile Test Programs Only
+
+ $ make check-programs
+
+## Fuzz Targets
+
+Build and run fuzz targets (requires clang):
+
+ $ ./tools/config-gen fuzz
+ $ make check
+
+## Environment Variables
+
+`TS_COMMAND` — override the default command for `make check`:
+
+ $ make check TS_COMMAND="true" # build deps only, skip tests
+
+`TS_OPTS` — pass options to `run.sh`:
+
+ $ make check TS_OPTS="--parallel=1 utmp"
+
+`TS_OPT_testdir_[testscript_]fake="yes|no"` — skip tests:
+
+ $ make check TS_OPT_fdisk_fake="yes" # skip all fdisk tests
+ $ make check TS_OPT_fdisk_bsd_fake="yes" # skip only fdisk/bsd
+ $ make check TS_OPT_fdisk_fake="yes" TS_OPT_fdisk_bsd_fake="no" # skip all fdisk except bsd
+
+`TS_OPT_testdir_[testscript_]known_fail="yes|no"` — mark tests as known
+failures (test runs but negative results are ignored).
+
+`TS_OPT_testdir_[testscript_]verbose="yes|no"` — set verbosity.
+
+`TS_OPT_testdir_[testscript_]memcheck="yes|no"` — run with valgrind.
+
+## External Services
+
+- Coveralls: https://coveralls.io/github/util-linux/util-linux
+- Coverity Scan: https://scan.coverity.com/projects/karelzak-util-linux
+- Fossies codespell: https://fossies.org/linux/test/util-linux-master.tar.gz/codespell.html
+- OSS-Fuzz: https://oss-fuzz.com/coverage-report/job/libfuzzer_asan_util-linux/latest
+- CIFuzz: https://github.com/util-linux/util-linux/actions?query=workflow%3ACIFuzz
+++ /dev/null
-util-linux build system
-=======================
-
- - the build system is non-recursive, individual subdirectories use
- Makemodule.am files. These files are merged together by automake
- into one global Makefile in the top-level directory
-
- - all final build results (binaries, libtool scripts) are stored in top-level
- source directory
-
- - all Makemodule.am files have to be designed as top-level makefiles, it
- means with full paths (e.g. foo_SOURCES = subdir/foo.c)
-
- - always use '+=' operator for global variables (e.g. bin_PROGRAMS += foo)
-
- - use libcommon.la (without path!) for lib/ stuff (e.g. foo_LDADD = libcommon.la)
-
- - for libblkid, libuuid and libmount use lib<name>.la in _LDADD and
- -I$(ul_lib<name>_incdir) in _CFLAGS, for example
-
- foo_LDADD = libmount.la
- foo_CFLAGS = -I$(ul_libmount_incdir)
-
- - always use suffixes for hooks, for example
-
- install-exec-hook-foo:
- ln -sf foo foooo
-
- INSTALL_EXEC_HOOKS += install-exec-hook-foo
-
-
- - all util-linux specific autoconf macros use UL_ prefix
-
- - utils in Makefile.am files are enabled/disabled according to BUILD_<NAME>
- conditions (AM_CONDITIONAL), for example:
-
- if BUILD_HWCLOCK
- ...
- endif
-
- - "if BUILD_<NAME>" blocks are never nested within another "if BUILD_<NAME>",
- all dependencies have to be resolved in configure.ac (see UL_REQUIRES_BUILD())
-
- - all BUILD_<NAME> in configure.am are always based on build_<name> variables,
- for example:
-
- AM_CONDITIONAL([BUILD_HWCLOCK], test "x$build_hwclock" = xyes)
-
- the $build_<name> should be available in whole configure script
-
- - AC_ARG_ENABLE() status is always stored in $enable_<name> variable, possible
- setting:
-
- "check" - util/feature is optional, if any subcomponent (function, lib,
- ...) is missing a warning is printed and the util/feature is
- disabled
-
- "yes" - util/feature is required, if any subcomponent (function, lib,
- ...) is missing an error is printed and ./configure aborted
-
- "no" - the util/feature is unwanted
-
- The default status is always defined by UL_DEFAULT_ENABLE() and it might be
- globally modified by $ul_default_estate (see AC_ARG_ENABLE([all-programs])).
-
- - it's possible to disable all programs, but enable just one (or more)
- explicitly specified, for example:
-
- ./configure --disable-all-programs --enable-hwclock
-
- - some basic scenarios for the ./configure script are defined in the
- tools/config-gen.d/ directory. If you want to use these predefined scenarios
- then call
-
- ./tools/config-gen [<scenario> ...]
-
- for example
-
- ./tools/config-gen all selinux
-
- will build all utils with enabled selinux support. You can also define some
- CFLAGS, for example:
-
- CFLAGS=$(rpm --eval '%optflags') ./tools/config-gen all
-
- will use the default distro flags.
-
- WARNING: config-gen is not designed for end-user or downstream distributions!
- It's for development purpose only. All end-users and downstream have
- to use standard ./configure script only.
-
- - the tools/config-gen script is also used for build system regression tests,
- the test is not enabled by default, you have to use
-
- tests/run.sh build-sys --force
+++ /dev/null
-The common case
-
- ./autogen.sh && ./configure && make
-
- If something fails read the last lines. Typical reason to
- fail is a missing dependency, such as libtool or gettext.
-
- make install-strip
-
- Note that on the production systems it is strongly recommended to use
- "make install-strip" to install binaries and libraries. The result
- from the standard "make install" may produce large binaries with
- unnecessary symbols.
-
-Autotools
-
- `./autogen.sh' generates all files needed to compile
- and install the code (run it after checkout from git)
-
- `make distclean' removes all unnecessary files, but the
- code can still be recompiled with "./configure; make"
-
- `make dist-gzip' (or -bzip2) creates a tarball that can
- be configured and compiled without running `./autogen.sh'
-
-Compiling
-
- Use SUID_CFLAGS and SUID_LDFLAGS when you want to define
- special compiler options for typical suid programs, for
- example:
-
- ./configure SUID_CFLAGS="-fpie" SUID_LDFLAGS="-pie"
-
- The SUID_* feature is currently supported for chfn, chsh,
- newgrp, su, write, mount, and umount.
-
- Use DAEMON_CFLAGS and DAEMON_LDFLAGS when you want to define
- special compiler options for daemons; supported for uuidd.
-
- Use SOLIB_CFLAGS and SOLIB_LDFLAGS when you want to define
- special compiler options for shared libraries; supported for
- libmount, libblkid and libuuid.
-
- FIXME: add notes about klib and uClib.
-
-
-Compile certain portion
-
- See ./configure --help and use --disable-* and --enable-* options.
-
- It's also possible to disable all the programs and enable only wanted.
- For example:
-
- ./configure --disable-all-programs --enable-fallocate
-
- Note that the configure script tracks dependencies between libs and
- tools. Always see warning messages and follow error messages if any
- dependence is necessary. For example to compile mount(8) you need also
- libmount, libblkid and libuuid:
-
- ./configure --disable-all-programs --enable-mount --enable-libmount \
- --enable-libblkid --enable-libuuid
-
-
-Static linking
-
- Use --enable-static-programs[=LIST] configure option when
- you want to use statically linked programs.
-
- Note, mount(8) uses get{pw,gr}nam() and getpwuid()
- functions for translation from username and groupname to
- UID and GID. These functions could be implemented by
- dynamically loaded independent modules (NSS) in your libc
- (e.g. glibc). These modules are not statically linked to
- mount(8) and mount.static is still using dlopen() like
- dynamically linked version.
-
- The translation won't work in environment where NSS
- modules are not installed.
-
- For example normal system (NSS modules are available):
-
- # ./mount.static -v -f -n -ouid=kzak /mnt/foo
- LABEL=/mnt/foo on /mnt/foo type vfat (rw,uid=500)
- ^^^^^^^
- and without NSS modules:
-
- # chroot . ./mount.static -v -f -n -ouid=kzak /mnt/win
- LABEL=/mnt/win on /mnt/win type vfat (rw,uid=kzak)
- ^^^^^^^^
+++ /dev/null
-CONTENTS
- Sending Patches
- Patching Process
- Email Format
- Coding Style
- Options
- Various Notes
- Standards Compliance
-
-Sending Patches
-
- * send your patches to the mailing list (see ../README) or by
- github.com pull request.
-
- * email is accepted as an inline patch with, or without, a git pull
- request. Pull request emails need to include the patch set for review
- purposes. See howto-pull-request.txt and ../README for git repository
- instructions.
-
- * email attachments are difficult to review and not recommended.
- Hint: use git send-email.
-
- * one patch per email.
- See Email Format.
-
- * many small patches are preferred over a single large patch. Split
- patch sets based upon logical functionality. For example: #endif mark
- ups, compiler warnings, and exit code fixes should all be individual
- small patches.
-
- * don't include generated (autotools) files in your patches.
- Hint: use 'git clean -Xd'.
-
- * don't include po/ (translations) changes to the upstream patches.
- The po/ stuff is maintained on https://translationproject.org/domain/util-linux.html
- and updated always before the next release.
-
- * neutrality: the files in util-linux should be distribution-neutral.
- Packages like RPMs, DEBs, and the rest, are not provided. They should
- be available from the distribution.
-
-Repositories & Branches
-
- * Primary repository is on kernel.org:
- git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
-
- * Backup repository at github.com:
- git clone https://github.com/util-linux/util-linux.git
-
- We use this repository to backup kernel.org and for PULL REQUESTS,
- issues tracking. The master and stable branches are always pushed to
- the both repositories in the same time.
-
- It's recommended to use github.com for development.
-
- * Branches:
-
- master - continuous development
- stable/vX.Y - stable releases
-
- Since version 2.40, the "master" branch remains continuously open and is
- never subjected to feature freezes. The stabilization process for
- the upcoming release is exclusively conducted within the "stable/" branches.
- Upon branching from "master" to "stable/vX.Y," a new tag vX.Y+1-devel
- is generated to serve as placeholder for git-based versioning (refer to
- tools/git-version-gen). Subsequently, changes specific to the new release
- (such as po/ updates) are selectively cherry-picked from "stable/vX.Y" to
- "master" after the final release.
-
-Patching Process
-
- * announce it on the mailing list when you are going to work with some
- particular piece of code for a long time. This helps others to avoid
- massive merge conflicts. Small or quick work, does not need to be
- announced.
-
- * make sure that after applying your patch the file(s) will compile
- without errors.
-
- * test that the previously existing program behavior is not altered. If
- the patch intentionally alters the behavior explain what changed, and
- the reason for it, in the changelog/commit message.
-
- * only submit changes that you believe are ready to merge. To post a
- patch for peer review only, state it clearly in the email and use
- the Subject: [PATCH RFC] ...
-
- * incorporate reviewer comments in the patches. Resubmitting without
- changes is neither recommended nor polite.
-
- * resubmission can be partial or complete. If only a few alterations are
- needed then resubmit those particular patches. When comments cause a
- greater effect then resubmit the entire patch set.
-
- * When resubmitting use the email Subject: [PATCH v2] ...
- Hint: use the --subject-prefix='PATCH v2' option with 'git format-patch'
-
- * using a git repository for (re)submissions can make life easier.
- See howto-pull-request.txt and ../README.
-
- * all patch submissions are either commented, rejected, or accepted.
- If the maintainer rejects a patch set it is pointless to resubmit it.
-
-Email Format
-
- * Subject: [PATCH] subsystem: description.
-
- * Start the message body with an explanation of the patch, that is, a
- changelog/commit entry.
-
- * if someone else wrote the patch, they should be credited (and
- blamed) for it. To communicate this, add a line like:
-
- From: John Doe <jdoe@wherever.com>
-
- * add a Signed-off-by line.
- Hint: use git commit -s
-
- The sign-off is a simple line at the end of the explanation for the
- patch; which certifies that you wrote it or otherwise have the
- right to pass it on as an open-source patch. The rules are pretty
- simple; if you can certify the following:
-
- By making a contribution to this project, I certify that:
-
- (a) The contribution was created in whole or in part by me and I
- have the right to submit it under the open source license
- indicated in the file; or
-
- (b) The contribution is based upon previous work that, to the best
- of my knowledge, is covered under an appropriate open source
- license and I have the right under that license to submit that
- work with modifications, whether created in whole or in part
- by me, under the same open source license (unless I am
- permitted to submit under a different license), as indicated
- in the file; or
-
- (c) The contribution was provided directly to me by some other
- person who certified (a), (b) or (c) and I have not modified
- it.
-
- (d) I understand and agree that this project and the contribution
- are public and that a record of the contribution (including
- all personal information I submit with it, including my
- sign-off) is maintained indefinitely and may be redistributed
- consistent with this project or the open source license(s)
- involved.
-
- Then you just add a line like:
-
- Signed-off-by: Random J Developer <random@developer.example.org>
-
- Use your real name (sorry, no pseudonyms or anonymous contributions.)
-
- * Next a single line beginning with three hyphen-minus characters (---)
- and nothing else.
-
- * Followed by the unified diff patch.
-
- Note: the mailing list will reject certain content. See ../README.
-
-Coding Style
-
- * the preferred coding style is based on the linux kernel coding-style.
- Available here:
-
- https://docs.kernel.org/process/coding-style.html
-
- * use 'FIXME:' with a good description, if you want to inform others
- that something is not quite right, and you are unwilling to fix the
- issue in the submitted change.
-
- * do not use `else' after non-returning functions. For
- example:
-
- if (this)
- err(EXIT_FAIL, "this failed");
- else
- err(EXIT_FAIL, "that failed");
-
- Is wrong and should be written:
-
- if (this)
- err(EXIT_FAIL, "this failed");
- err(EXIT_FAIL, "that failed");
-
- * when you use 'if' short-shorthand make sure it does not wrap into
- multiple lines. In case the shorthand does not look good on one line
- use the normal "if () else" syntax.
-
- * To avoid whitespace errors, consider installing an EditorConfig plugin
- (https://editorconfig.org/) into your favorite editor or IDE.
-
-Options
-
- * The rule of thumb for options is that once they exist, you may not
- change them, nor change how they work, nor remove them.
-
- * The following options are well-known, and should not be used for any
- other purpose:
-
- -h, --help display usage and exit
- -V, --version display version and exit
-
- * Some commands use peculiar options and arguments. These will continue
- to be supported, but anything like them will not be accepted as new
- additions. A short list of examples:
-
- Characters other than '-' to start an option. See '+' in 'more'.
-
- Using a number as an option. See '-<number>' in 'more'.
-
- Long options that start with a single '-'. See 'setterm'.
-
- '-?' is not a synonym for '--help', but is an unknown option
- resulting in a suggestion to try --help due to a getopt failure.
-
-Various Notes
-
- * util-linux does not use kernel headers for file system super
- blocks structures.
-
- * patches relying on kernel features that are not in Linus Torvalds's
- tree are not accepted.
-
-Standards Compliance
-
- Some of the commands maintained in this package have Open Group
- requirements. These commands are:
-
- cal
- col
- ipcrm
- ipcs
- kill
- line
- logger
- mesg
- more
- newgrp
- pg
- renice
-
- If you change these tools please make sure it does not create a conflict
- with the latest standard. For example, it is not recommended to add
- short command line options before they are part of the standard.
- Introducing new long options is acceptable.
-
- The Single UNIX(TM) Specification, Version 2
- Copyright (C) 1997 The Open Group
-
- https://pubs.opengroup.org/onlinepubs/7908799/xcuix.html
-
+++ /dev/null
-Debugging util-linux programs
-=============================
-
-How to deal libtool
--------------------
-
-There are considerations to be made when profiling or debugging some programs
-found in the util-linux package. Because wrapper scripts are used for the
-binaries to make sure all library dependencies are met, you cannot use tools
-such as gdb or valgrind directly with them.
-
-Let's take for example the mount command:
-
- $> cd /path/to/util-linux
- $> file mount/mount
- mount/mount: Bourne-Again shell script text executable
-
-The binary itself is located in the mount/.libs/ directory:
-
- $> file mount/.libs/mount
- mount/.libs/mount: ELF 64-bit LSB executable, x86-64, version 1 \
- (SYSV), dynamically linked (uses shared libs) [...]
-
-When this command is run, there's a library dependency error:
-
- $> mount/.libs/mount
- mount/.libs/mount: /lib/libblkid.so.1: version `BLKID_2.20' not found \
- (required by mount/.libs/mount)
-
-To overcome this we need set the LD_LIBRARY_PATH variable to read the path of
-the shared lib found in the sources, and not system-wide:
-
- $> export LD_LIBRARY_PATH=$PWD/libblkid/src/.libs/:$LD_LIBRARY_PATH
-
-Now external debugging tools can be run on the binary.
-
-Happy hacking!
-Davidlohr Bueso, August 2011
-
-
-The libmount & libblkid
------------------------
-
-Both of the libraries can be debugged by setting an environment variable
-consisting of a number. The number will be used as a bit mask, so the more 1 the
-higher the debugging level. Search for `DEBUG' from files
-
- libblkid/src/blkidP.h
- libmount/src/mountP.h
-
-to see what the different bits mean. At the time of writing this the following
-enabled full debug.
-
- export LIBBLKID_DEBUG=all
- export LIBMOUNT_DEBUG=all
- export LIBFDISK_DEBUG=all
- export LIBSMARTCOLS_DEBUG=all
-
-The libblkid reads by default /etc/blkid.conf which can be overridden by the
-environment variable BLKID_CONF. See manual libblkid/libblkid.3 for details
-about the configuration file.
-
-Block device information is normally kept in a cache file (see blkid man page
-for more information about the cache file location) that can be overridden by
-the environment variable BLKID_FILE.
-
-To libmount uses three paths, which can be overridden by using environment
-variables. Notice that these environment variables are ignored for non-root
-users.
-
- env variable if not set defaults to
- LIBMOUNT_FSTAB /etc/fstab
- LIBMOUNT_MTAB /etc/mtab
- LIBMOUNT_UTAB /run/mount/utab or /dev/.mount/utab
+++ /dev/null
-Since v2.37 util-linux project uses asciidoc format to maintain man pages.
-See man-common/manpage-stub.adoc for more details.
+++ /dev/null
-Introduction
-------------
-
-These instructions are written for contributors who tend to send lots of
-changes. The basics from the howto-contribute.txt file are assumed to be
-read and understood by the time this file becomes useful.
-
-In these instructions, the upstream remote repository is called
-'origin' and 'yourgit' is the contributor repository.
-
-Setup
------
-
-1. Find a git server that can be reached from anywhere on the internet
-anonymously. Github, for example, is a popular choice.
-
-2. Create your own util-linux contributor repository, and push an upstream
-clone there:
-
-cd ~/projects
-git clone git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git
-cd util-linux
-git remote add yourgit git@github.com:yourlogin/util-linux.git
-git push yourgit
-
-
-Branches
---------
-
-1. The name of your branch isn't crucial, but if you intend to contribute
-regularly, it's beneficial to establish a naming convention that works well for
-you. For instance, consider prefixing your branch name with the subsystem's
-name, such as blkid, libmount, etc.
-
-2. Avoid using the 'master' branch for your contributions. The 'master' branch
-should be reserved for staying synchronized with the upstream repository.
-
-3. Once you've completed your work, push your branch to your remote Git server:
-
-git checkout master
-git branch textual
-# spend most of the effort here
-git push yourgit textual:textual
-
-5. Do not worry if you used a stupid-and-wrong branch name, it can be fixed
-before submission:
-
-git branch -m stupid-and-wrong brilliant
-git push yourgit brilliant:brilliant :stupid-and-wrong
-
-
-Stay up to date
----------------
-
-1. Ensure you have the latest from all remote repositories.
-
-2. Merge upstream 'master' branch if needed to your local 'master'.
-
-3. Rebase your working contribution branches.
-
-4. Push the changes to 'yourgit':
-
-git fetch --all
-git log --graph --decorate --pretty=oneline --abbrev-commit --all
-
-5. If you notice upstream has changed while you were busy with your
-changes rebase on top of the master, but before that:
-
-6. Push a backup of your branch 'textual' to 'yourgit', then:
-
-git checkout master
-git merge origin/master
-git checkout textual
-git rebase master
-
-If rebase reports conflicts, fix the conflicts. If the rebase conflict is
-difficult to fix, rebase --abort is a good option, or recover from
-'yourgit'; either way, there is some serious re-work ahead with the
-change set.
-
-7. Assuming rebase went fine, push the latest to 'yourgit':
-
-git push yourgit master:master
-git push yourgit --force textual:textual
-
-The contributor branch tends to need --force every now and then; don't be
-afraid to use it.
-
-8. Push error with master branch
-
-If 'master' needs --force, something is really messed up. In that
-case it is probably wise to abandon(*) local clone, and start all
-over from cloning upstream again. Once the upstream is cloned, add
-'yourgit' remote again and push:
-
-git push --mirror yourgit
-
-But be WARNED: The --mirror will nuke all of your stuff in 'yourgit'; that can
-cause data loss. (*)So don't remove the local clone, just move the directory
-to the broken repository area.
-
-
-Sending the pull request
-------------------------
-
-1. When you are happy with your changes, sleep over night. This is not a
-speed competition, and for some reason looking at the changes the next day
-often makes one realize how things could be improved. This way, you avoid
-changing the changes (that is always confusing).
-
-2. Check the next day that the changes compile without errors or warnings,
-and that regression tests run fine:
-
-make clean &&
-make -j3 &&
-make check
-
-Note that regression tests will not cover all possible cases, so you most
-likely need to use the commands, features, and fixes you did manually.
-
-3. If you need to change something:
-
-git rebase -i master
-# change something
-git push -f yourgit textual:textual
-
-4. You have two ways to send your pull request:
-
-4.1 Github pull request (recommended)
-
-This is the recommended way for changes. All you need is to press the
-"Pull request" button on GitHub.
-
-4.2. Send your work to the mailing list (optional)
-
-Assuming the changes look good, send them to the mailing list. Yes, all
-of them! Sending a pull request with GitHub is not visible to project
-contributors, and they will not have a chance to review your changes.
-
-Sending only the pull request, i.e., not each patch, to the mailing list
-is also bad. Nothing is as good as seeing the changes as they are, and
-being able to find them from with your favorite web search engine from
-the mailing list archive. Obviously, the pull request content does not get
-indexed, and that is why it is worse.
-
-git format-patch --cover-letter master..textual
-git request-pull upstream/master https://github.com/yourlogin/util-linux.git textual > tempfile
-
-Take from the 'tempfile' the header:
-
-----------------------------------------------------------------
-The following changes since commit 17bf9c1c39b4f35163ec5c443b8bbd5857386ddd:
-
- ipcrm: fix usage (2015-01-06 11:55:21 +0100)
-
-are available in the git repository at:
-
- https://github.com/yourlogin/util-linux.git textual
-----------------------------------------------------------------
-
-Copy and paste it to a 0000-cover-letter.patch file somewhere near 'BLURB
-HERE'. The rest of the 'request-pull' output should be ignored.
-
-In the same file, fix the Subject: line to have reasonable description, for
-example:
-
-Subject: [PATCH 00/15] pull: various textual improvements
-
-
-Feedback and resubmissions
---------------------------
-
-1. If you sent each patch to the mailing list, you can see which ones got
-responses. If the feedback results in changes to the submission then rebase,
-perform the changes, and push again to your remote:
-
-# you probably should use 'Stay up to date' instructions now
-git checkout textual
-git rebase master -i
-# edit something
-git add files
-git commit --amend
-# Add 'Reviewed-by:', 'Tested-by:', 'Signed-off-by:', 'Reference:', and
-# other lines near signoff when needed. Attributing the reviewers is a
-# virtue, try to do it.
-git rebase --continue
-git push -f yourgit textual:textual
-
-2. Send a message to the mailing list that the submitted change has changed, and
-that the new version can be found from:
-
-https://github.com/yourlogin/util-linux/commit/0123456789abcdef0123456789abcdef01234567
-
-3. There is no need to update the pull request cover letter. The project
-maintainer has done enough of this stuff to know what to do.
-
-
-Repository maintenance
-----------------------
-
-1. When your remote branch is merged, or you get a final rejection, it is time
-to clean it up:
-
-git branch textual -d
-git push yourgit :textual
-
-2. If you have other contributor repositories configured, you may also
-want to clean up the branches the others are done with:
-
-for I in $(git remote); do
- echo "pruning: $I"
- git remote prune $I
-done
-
-3. When all of your contributions are processed, you should tidy up the
-git's guts:
-
-git reflog expire --all
-git gc --aggressive --prune=now
-
-Warning: Tidying is not a good idea while you are actively working
-with the change set. You never know when you'll need to recover something
-from the reflog, so keep that option available until you know the reflog is
-not needed.
-
-
-More branches, on top of branches, on top of ...
-------------------------------------------------
-
-Here is one way of laying out multiple branches:
-
-git log --graph --decorate --pretty=oneline --abbrev-commit --all
-* 13bfff3 (HEAD, docs-update) docs: small improvements to howto-contribute.txt
-* 5435d28 (sami/more, more) more: do not call fileno() for std{in,out,err} streams
-* 3e1ac04 more: remove unnecessary braces
-* c19f31c more: check open(3) return value
-* 651ec1b more: move skipping forewards to a function from command()
-* bf0c2a7 more: move skipping backwards to a function from command()
-* 53a438d more: move editor execution to a function from command()
-* b11628b more: move runtime usage output away from command()
-* 6cab04e more: avoid long else segment in prbuf()
-* a2d9fbb more: remove 'register' keywords
-* c6b2d29 more: remove pointless functions
-* b41fe34 more: remove function like preprocessor defines
-* 1aaa1ce more: use paths.h to find bourne shell and vi editor
-* 016a019 more: return is statement, not a function
-* ff7019a more: remove dead code and useless comments
-* 1705c76 more: add struct more_control and remove global variables
-* 3ad4868 more: reorder includes, declarations, and global variables
-* 7220e9d more: remove function declarations - BRANCH STATUS: WORK IN PROGRESS
-* 04b9544 (sami/script) script: add noreturn function attributes
-* e7b8d50 script: use gettime_monotonic() to get timing file timestamps
-* 11289d2 script: use correct input type, move comment, and so on
-* 524e3e7 script: replace strftime() workaround with CFLAGS = -Wno-format-y2k
-* 0465e7f script: move do_io() content to small functions
-* 751edca script: add 'Script started' line always to capture file
-* f831657 script: remove io vs signal race
-* eefc1b7 script: merge doinput() and output() functions to do_io()
-* 9eba044 script: use poll() rather than select()
-* a6f04ef script: use signalfd() to catch signals
-* 4a86d9c script: add struct script_control and remove global variables
-* d1cf19c script: remove function prototypes
-* 6a7dce9 (sami/2015wk00) fsck.minix: fix segmentation fault
-* 5e3bcf7 lslocks: fix type warning
-* 3904423 maint: fix shadow declarations
-* 17bf9c1 (upstream/master, sami/master, kzgh/master, master) ipcrm: fix usage
-[...]
-
-The above gives a hint to maintainers what the preferred merge order is.
-The branches '2015wk00' and 'script' are ready to be merged, and they
-were sent to the mailing list.
-
-The 'more' branch was not submitted at the time of writing this text.
-Marking that the branch is not ready is clearly done in the commit subject;
-that will need some rebasing before submission.
-
-A good order for the branches is:
-
-1. First the minor and safe changes.
-2. Then the ready but less certain stuff.
-3. Followed by work-in-progress.
-
-If you go down this route, you will get used to typing a lot of:
-
-git rebase previous-branch
-git push -f yourgit branch:branch
-
-Alternatively, rebase each branch on top of origin/master, but this is not
-quite as good. How can you ensure your own changes are not in conflict
-with each other? And there is no hint of the preferred merging order.
+++ /dev/null
-
- util-linux regression tests
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- It's expected that for each invasive change or important bugfix you will
- include a test to your patch.
-
- Compile binaries, libs, extra test programs and run the basic tests:
-
- $ make check
-
- Compile extra test programs only:
-
- $ make check-programs
-
- Note that the configure option --disable-static disables many of libmount and
- libblkid unit tests.
-
- Run all tests including tests that require root permissions:
-
- # cd tests
- # ./run.sh [options, see --help]
-
- Alternatively using sudo and make:
-
- $ make check-programs
- $ sudo -E make check TS_OPTS="--parallel=1"
-
- note that as root you have to manually remove output and diff directories
-
- # rm -rf output diff
-
- or run 'make clean' as root.
-
-
- Run subset of tests:
-
- $ cd tests
- $ ./run.sh <test_directory-name>
-
- for example:
-
- $ ./run.sh blkid
- $ ./run.sh libmount
-
- or individual test script, for example:
-
- $ ./ts/cal/year
-
- The tests is possible to exclude by ./run.sh --exclude=<list> where the
- <list> is blank separated test names in format "testdir/testname", for example:
-
- $ ./run.sh --exclude="mount/move"
-
- The --exclude is evaluated by the ./run.sh script only. See below
-
- TS_OPT_testdir_[testscript_]fake=
-
- environment variable which provides more powerful functionality to skip tests.
-
-
- *** WARNING for root users ***
-
- The tests touch your /etc/fstab, initialize loop devices or scsi_debug devices
- if executed with root permissions.
-
- Please, be careful and use these tests only for development and never on
- production system.
-
-fuzz targets
-------------
-
-The fuzz targets can be built and run along with the other tests (after installing
-clang):
-
- $ ./tools/config-gen fuzz
- $ make check
-
-environment variables
----------------------
-
-TS_COMMAND
-
- Evaluated by "make check" to override the default command (run.sh).
- Example:
- - build all test dependencies, but skip the actual test
- $ make check TS_COMMAND="true"
-
-TS_OPTS
-
- Evaluated by "make check" to pass options.to run.sh (see ./run.sh --help).
- Examples:
- - run utmp tests only
- $ make check TS_OPTS="--parallel=1 utmp"
-
-TS_OPT_testdir_[testscript_]fake="<yes|no>"
-
- Evaluated by any test script to skip certain tests.
- Examples:
- - skip all the tests within "fdisk" test-directory:
- $ make check TS_OPT_fdisk_fake="yes"
-
- - skip only "fdisk/bsd" test:
- $ make check TS_OPT_fdisk_bsd_fake="yes"
-
- - skip all "fdisk" tests except fdisk/bsd:
- $ make check TS_OPT_fdisk_fake="yes" TS_OPT_fdisk_bsd_fake="no"
-
-TS_OPT_testdir_[testscript_]known_fail="<yes|no>"
-
- Similar usage like TS_OPT_*_fake above. "known_fail" means that the given
- test will run but (negative) results will be ignored. The build log and test
- diffs will still remind you about the issue.
-
-TS_OPT_testdir_[testscript_]verbose="<yes|no>"
-
- Set verbosity for certain tests. Similar usage like TS_OPT_*_fake above.
-
-TS_OPT_testdir_[testscript_]memcheck="<yes|no>"
-
- Run certain tests with valgrind. Similar usage like TS_OPT_*_fake above.
-
-
-External services
------------------
-
-Coveralls coverage reports
-
- URL: https://coveralls.io/github/util-linux/util-linux
-
-lgtm CI - automatically executed security code analysis
-
- URL: https://lgtm.com/projects/g/util-linux/util-linux/
-
-Coverity Scan
-
- URL: https://scan.coverity.com/projects/karelzak-util-linux
-
-Fossies codespell report
-
- URL: https://fossies.org/linux/test/util-linux-master.tar.gz/codespell.html
-
-OSS-Fuzz
-
- URL: https://google.github.io/oss-fuzz/
- URL: https://oss-fuzz-build-logs.storage.googleapis.com/index.html#util-linux
- URL: https://oss-fuzz.com/coverage-report/job/libfuzzer_asan_util-linux/latest
-
-CIFuzz
-
- URL: https://google.github.io/oss-fuzz/getting-started/continuous-integration/
- URL: https://github.com/util-linux/util-linux/actions?query=workflow%3ACIFuzz
+++ /dev/null
-
-Example file
-------------
-
-Refer to the ./boilerplate.c example file while reading this howto.
-
-
-How a usage text is supposed to look
-------------------------------------
-
-The usage() output format is: Usage section, command description one-liner,
-Options section (see below), special sections like 'Available columns', and
-the last line is either the man page reference or an empty line. The output
-begins with, and each of the above are separated by, one empty line.
-
-The Usage section contains the synopsis line that describes how to compose
-the command. Sometimes you may need multiple synopsis lines (see below).
-
-Only the synopsis and option lines are indented. Indent is one space (0x40).
-Option lines do not use line-ending punctuation. Other sentences do.
-
-Notations: diamond brackets are used to mark an argument to be filled in;
-square brackets are used to mark anything that is optional, such as optional
-command arguments, or optional option arguments. In the later case the '='
-character is required in between the option and argument with no whitespace;
-three consecutive dots means the unlimited repetition of the preceding.
-
-The short option is always written first, followed by the long option. They
-are separated with a comma and one space. Lonely short or long options do
-not affect their alignment. That is, they must be in their respective column.
-
-Below, in between the snips, is an example of what the usage output should
-look like.
-
--- snip
-
-Usage:
- program [options] <file> [...]
-
-Short program description, ideally one line only.
-
-Options:
- -n, --no-argument option does not use argument
- --optional[=<arg>] option argument is optional
- -r, --required <arg> option requires an argument
- -z no long option
- --xyzzy a long option only
- -e, --extremely-long-long-option
- use next line for description when needed
- -l, --long-explanation an example of very verbose, and chatty option
- description on two, or multiple lines, where the
- continuation lines are indented by two spaces
- -f, --foobar next option description resets indent
-
- -h, --help display this help and exit
- -V, --version output version information and exit
-
-For more details see program(1).
--- snip
-
-
-Option descriptions
--------------------
-
-This information also applies to other option-like arguments. That is,
-arguments starting with '-'. Such as: functions, commands, and so forth.
-
-An option description should not exceed the width of 80 characters. If
-you need a longer description, use multiple lines and indentation.
-
-The description text begins from the point of the longest option plus two
-spaces. If adding a new option would necessitate a re-indentation of the
-descriptions, it either has to be done, or the new option should begin its
-description on the next line. Usually the later is better.
-
-An argument is preferably worded appropriately. For example, if an option
-expects a number as argument, '<num>' is a suitable argument indicator.
-
-The order of the options has no special meaning, with the exception of
---help and --version which are expected to be last ones in the list.
-
-
-Usage function
---------------
-
-The usage() function will never return. It must only be called by -h/--help.
-All other cases use errtryhelp(EXIT_FAILURE).
-
-Section headers, man page, version, help, and other components of usage()
-have string constants defined in 'include/c.h' which must be used. See the
-example file listed at the top of this document. The help and version options
-are combined into a single macro which takes an argument for the column that
-their descriptions will begin on: USAGE_HELP_OPTIONS(<num>). This allows
-them to align properly with the other options.
-
-In the code, all option strings must start at the same position.
-See here what this means:
-
- printf(out, _(" -x[=<foo>] default foo is %s"), x);
- puts( _(" -y some text"), out);
-
-Be nice to translators. One gettext entry should be one option, no more,
-no less. For example:
-
- puts(_(" --you-there be nice\n"), out);
- puts(_(" -2 <whom> translators\n"), out);
- puts(_(" -t, --hey are doing a job that we probably cannot,"
- " or how is your klingon?\n"), out);
-
-When existing usage output is changed, and it happens to be one big text,
-split it into chunks the size of one option. The extra work this will entail
-for translators will pay off later; the next string change will not force a
-search of the long fuzzy text for what was changed, where, how, and whether
-it was the only change.
-
-
-Synopsis
---------
-
-You may need to use multiple synopsis lines to show that a command does
-fundamentally different things depending on the options and/or arguments.
-For example, ionice either changes the priority of a running command, or
-executes a program with a defined priority. Therefore it is reasonable
-to have two synopsis lines:
-
- ionice [options] -p <pid> ...
- ionice [options] <command> [<arg> ...]
-
-Note that the synopsis is not meant to be a repetition of the options
-section. The fundamental difference in execution is a bit difficult to
-define. The command author, package maintainer or patch submitter will
-usually know when it should be done that way.
-
-
projects / thirdparty / util-linux.git / commitdiff
