These are the GNU core utilities.  This package is the union of
the GNU fileutils, sh-utils, and textutils packages.

Most of these programs have significant advantages over their Unix
counterparts, such as greater speed, additional options, and fewer
arbitrary limits.

The programs that can be built with this package are:

  [ arch b2sum base32 base64 basename basenc cat chcon chgrp chmod chown
  chroot cksum comm coreutils cp csplit cut date dd df dir dircolors dirname
  du echo env expand expr factor false fmt fold groups head hostid hostname
  id install join kill link ln logname ls md5sum mkdir mkfifo mknod mktemp
  mv nice nl nohup nproc numfmt od paste pathchk pinky pr printenv printf ptx
  pwd readlink realpath rm rmdir runcon seq sha1sum sha224sum sha256sum
  sha384sum sha512sum shred shuf sleep sort split stat stdbuf stty sum sync
  tac tail tee test timeout touch tr true truncate tsort tty uname unexpand
  uniq unlink uptime users vdir wc who whoami yes

See the file NEWS for a list of major changes in the current release.

If you obtained this file as part of a "git clone", then see the
README-hacking file.  If this file came to you as part of a tar archive,
then see the file INSTALL for general compilation and installation
instructions, or README-install for system and coreutils specific instructions.

Like the rest of the GNU system, these programs mostly conform to
POSIX, with BSD and other extensions.  For closer conformance, or
conformance to a particular POSIX version, set the POSIXLY_CORRECT
and the _POSIX2_VERSION environment variables, as described in
the documentation under "Standards conformance".

The ls, dir, and vdir commands are all separate executables instead of
one program that checks argv[0] because people often rename these
programs to things like gls, gnuls, l, etc.  Renaming a program
file shouldn't affect how it operates, so that people can get the
behavior they want with whatever name they want.

Special thanks to Paul Eggert, Brian Matthews, Bruce Evans, Karl Berry,
Kaveh Ghazi, and François Pinard for help with debugging and porting
these programs.  Many thanks to all of the people who have taken the
time to submit problem reports and fixes.  All contributed changes are
attributed in the commit logs.

And thanks to the following people who have provided accounts for
portability testing on many different types of systems: Bob Proulx,
Christian Robert, François Pinard, Greg McGary, Harlan Stenn,
Joel N. Weber, Mark D. Roth, Matt Schalit, Nelson H. F. Beebe,
Réjean Payette, Sam Tardieu.

Thanks to Michael Stone for inflicting test releases of this package
on Debian's unstable distribution, and to all the kind folks who used
that distribution and found and reported bugs.

Note that each man page is now automatically generated from a template
and from the corresponding --help usage message.  Patches to the template
files (man/*.x) are welcome.  However, the authoritative documentation
is in texinfo form in the doc directory.


***************
Feature requests:
---------------

If you would like to add a new feature, please try to get some sort of
consensus that it is a worthwhile change.  One way to do that is to send
mail to coreutils@gnu.org including as much description and justification
as you can.  Based on the feedback that generates, you may be able to
convince us that it's worth adding.  Please also consult the list of
previously discussed but ultimately rejected feature requests at:
https://www.gnu.org/software/coreutils/rejected_requests.html


***************
Reporting bugs:
---------------

Send bug reports, questions, comments, etc. to bug-coreutils@gnu.org.
To suggest a patch, see the files README-hacking and HACKING for tips.

All of these programs except 'test' recognize the '--version' option.
When reporting bugs, please include in the subject line both the package
name/version and the name of the program for which you found a problem.

If you have a problem with 'sort', try running 'sort --debug', as it
can often help find and fix problems without having to wait for an
answer to a bug report.  If the debug output does not suffice to fix
the problem on your own, please compress and attach it to the rest of
your bug report.

IMPORTANT: if you take the time to report a test failure,
please be sure to include the output of running 'make check'
in verbose mode for each failing test.  For example,
if the test that fails is tests/df/df-P.sh, then you would
run this command:

  make check TESTS=tests/df/df-P.sh VERBOSE=yes SUBDIRS=. >> log 2>&1

For some tests, particularly perl tests, you can get even more detail by adding
DEBUG=yes. Then include the contents of the file 'log' in your bug report.


***************************************

There are many tests, but nowhere near as many as we need.
Additions and corrections are very welcome.

If you see a problem that you've already reported, feel free to re-report
it -- it won't bother us to get a reminder.  Besides, the more messages we
get regarding a particular problem the sooner it'll be fixed -- usually.
If you sent a complete patch and, after a couple weeks you haven't
received any acknowledgement, please ping us.  A complete patch includes
a well-written ChangeLog entry, unified (diff -u format) diffs relative
to the most recent test release (or, better, relative to the latest
sources in the public repository), an explanation for why the patch is
necessary or useful, and if at all possible, enough information to
reproduce whatever problem prompted it.  Plus, you'll earn lots of
karma if you include a test case to exercise any bug(s) you fix.
Here are instructions for checking out the latest development sources:

  https://savannah.gnu.org/git/?group=coreutils

For general documentation on the coding and usage standards
this distribution follows, see the GNU Coding Standards at:
https://www.gnu.org/prep/standards/

For any copyright year range specified as YYYY-ZZZZ in this package
note that the range specifies every single year in that closed interval.

Please see the file COPYING for copying conditions.

========================================================================

Copyright (C) 1998-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the "GNU Free
Documentation License" file as part of this distribution.

Building from a Git repository				-*- outline -*-

These notes intend to help people working on the checked-out sources.
These requirements do not apply when building from a distribution tarball.
If this package has a file HACKING, please also read that file for
more detailed contribution guidelines.

* Requirements

We've opted to keep only the highest-level sources in the Git repository.
This eases our maintenance burden (fewer merges etc.), but imposes more
requirements on anyone wishing to build from the just-checked-out sources.
(The requirements to build from a release are much less and are just
the requirements of the standard './configure && make' procedure.)
Specific development tools and versions will be checked for and listed by
the bootstrap script.  See README-prereq for specific notes on obtaining
these prerequisite tools.

Valgrind <https://valgrind.org/> is also highly recommended, if
Valgrind supports your architecture.  See also README-valgrind
(if present).

While building from a just-cloned source tree may require installing a
few prerequisites, later, a plain 'git pull && make' typically suffices.

* First Git checkout

You can get a copy of the source repository like this:

        $ git clone https://git.savannah.gnu.org/git/<packagename>
        $ cd <packagename>

where '<packagename>' stands for 'coreutils' or whatever other package
you are building.

To use the most-recent Gnulib (as opposed to the Gnulib version that
the package last synchronized to), do this next:

        $ git submodule foreach git pull origin master
        $ git commit -m 'build: update gnulib submodule to latest' gnulib

As an optional step, if you already have a copy of the Gnulib Git
repository, then you can use it as a reference to reduce download
time and file system space requirements:

        $ export GNULIB_SRCDIR=/path/to/gnulib

The next step is to get and check other files needed to build,
which are extracted from other source packages:

        $ ./bootstrap

And there you are!  Just

        $ ./configure --quiet #[--disable-gcc-warnings] [*]
        $ make
        $ make check

At this point, there should be no difference between your local copy,
and the Git master copy:

        $ git diff

should output no difference.

Enjoy!

[*] By default GCC warnings are enabled when building from Git.
If you get warnings with recent GCC and Glibc with default
configure-time options, please report the warnings to the bug
reporting address of this package instead of to bug-gnulib,
even if the problem seems to originate in a Gnulib-provided file.
If you get warnings with other configurations, you can run
'./configure --disable-gcc-warnings' or 'make WERROR_CFLAGS='
to build quietly or verbosely, respectively.
-----

* Submitting patches

If you develop a fix or a new feature, please send it to the
appropriate bug-reporting address as reported by the --help option of
each program.  One way to do this is to use vc-dwim
<https://www.gnu.org/software/vc-dwim/>), as follows.

  Run the command "vc-dwim --initialize" from the top-level directory
  of this package's git-cloned hierarchy.

  Edit the (empty) ChangeLog file that this command creates, creating a
  properly-formatted entry according to the GNU coding standards
  <https://www.gnu.org/prep/standards/html_node/Change-Logs.html>.

  Make your changes.

  Run the command "vc-dwim" and make sure its output (the diff of all
  your changes) looks good.

  Run "vc-dwim --commit".

  Run the command "git format-patch --stdout -1", and email its output
  in, using the output's subject line.

-----

Copyright (C) 2002-2023 Free Software Foundation, Inc.

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 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Please see the file INSTALL for generic build and installation instructions.
This file details coreutils and system specific build instructions.


*********************
Pre-C99 build failure
---------------------

In 2009 we added this requirement:
To build the coreutils from source, you must have a C99-conforming
compiler, due to the use of declarations after non-declaration statements
in several files in src/.  There is code in configure to find and, if
possible, enable an appropriate compiler.  However, if configure doesn't
find a C99 compiler, it continues nonetheless, and your build will fail.
There used to be a "c99-to-c89.diff" patch you could apply to convert
to code that even an old pre-c99 compiler can handle, but it was too
tedious to maintain, so has been removed.


***********************
HPUX 11.x build failure
-----------------------

A known problem exists when compiling on HPUX on both hppa and ia64
in 64-bit mode (i.e., +DD64) on HP-UX 11.0, 11.11, and 11.23.  This
is not due to a bug in the package but instead due to a bug in the
system header file which breaks things in 64-bit mode.  The default
compilation mode is 32-bit and the software compiles fine using the
default mode.  To build this software in 64-bit mode you will need
to fix the system /usr/include/inttypes.h header file.  After
correcting that file the software also compiles fine in 64-bit mode.
Here is one possible patch to correct the problem:

--- /usr/include/inttypes.h.orig	Thu May 30 01:00:00 1996
+++ /usr/include/inttypes.h	Sun Mar 23 00:20:36 2003
@@ -489 +489 @@
-#ifndef __STDC_32_MODE__
+#ifndef __LP64__


************************
OSF/1 4.0d and AIX build failures
------------------------

If you use /usr/bin/make on these systems, the build will fail due
to the presence of the "[" target.  OSF/1 make(1) appears to
treat "[" as some syntax relating to locks, while AIX make(1)
appears to skip the "[" target.  To work around these issues
the best solution is to use GNU make.  Otherwise, simply remove
all mention of "[$(EXEEXT)" from src/Makefile.


************************
32 bit time_t build failures
------------------------

Although 32-bit builds fail if that forces time_t to be 32 bits, this
can be fixed by using 64-bit builds.  For example, on AIX where GCC
defaults to 32 bits, one can use "./configure CC='gcc -maix64' AR='ar
-X64'"; similarly, on Solaris one can configure with CC='gcc -m64'.
If all else fails one can configure with --disable-year2038;
however, this will mishandle timestamps after 2038, and please file
bug reports for any such situations.


*************************************************
"make check" failure on IRIX 6.5 and Solaris <= 9
-------------------------------------------------

Using the vendor make program to run "make check" fails on these two systems.
If you want to run all of the tests there, use GNU make.



**********************
Running tests as root:
----------------------

If you run the tests as root, note that a few of them create files
and/or run programs as a non-root user, 'nobody' by default.
If you want to use some other non-root username, specify it via
the NON_ROOT_USERNAME environment variable.  Depending on the
permissions with which the working directories have been created,
using 'nobody' may fail, because that user won't have the required
read and write access to the build and test directories.
I find that it is best to unpack and build as a non-privileged
user, and then to run the following command as that user in order
to run the privilege-requiring tests:

  sudo env PATH="$PATH" NON_ROOT_USERNAME=$USER make -k check-root

If you can run the tests as root, please do so and report any
problems.  We get much less test coverage in that mode, and it's
arguably more important that these tools work well when run by
root than when run by less privileged users.



**********************
autotools considerations:
----------------------

WARNING:  Now that we use the ./bootstrap script, you should not run
autoreconf manually.  Doing that will overwrite essential source files
with older versions, which may make the package unbuildable or introduce
subtle bugs.

WARNING:  If you modify files like configure.in, m4/*.m4, aclocal.m4,
or any Makefile.am, then don't be surprised if what gets regenerated no
longer works.  To make things work, you'll have to be using appropriate
versions of the tools listed in bootstrap.conf's buildreq string.

On 2002-09-01, the GNU fileutils, textutils, and sh-utils
packages were merged into one, called the GNU coreutils.
See https://www.gnu.org/software/coreutils/coreutils.html for a description.
Here's the FAQ list:

  https://www.gnu.org/software/coreutils/faq/

For information on the mailing lists associated with the
coreutils package, including archive locations, see these:

  https://lists.gnu.org/mailman/listinfo/coreutils-announce
  https://lists.gnu.org/mailman/listinfo/bug-coreutils
  https://lists.gnu.org/mailman/listinfo/coreutils

This gives some notes on obtaining the tools required for development.
These tools can be used by the 'bootstrap' and 'configure' scripts,
as well as by 'make'.  They include:

- Autoconf   <https://www.gnu.org/software/autoconf/>
- Automake   <https://www.gnu.org/software/automake/>
- Bison      <https://www.gnu.org/software/bison/>
- Gettext    <https://www.gnu.org/software/gettext/>
- Git        <https://git-scm.com/>
- Gperf      <https://www.gnu.org/software/gperf/>
- Gzip       <https://www.gnu.org/software/gzip/>
- Help2man   <https://www.gnu.org/software/help2man/>
- M4         <https://www.gnu.org/software/m4/>
- Make       <https://www.gnu.org/software/make/>
- Perl       <https://www.cpan.org/>
- Tar        <https://www.gnu.org/software/tar/>
- Texinfo    <https://www.gnu.org/software/texinfo/>
- Wget       <https://www.gnu.org/software/wget/>
- XZ Utils   <https://tukaani.org/xz/>

It is generally better to use official packages for your system.
If a package is not officially available you can build it from source
and install it into a directory that you can then use to build this
package.  If some packages are available but are too old, install the
too-old versions first as they may be needed to build newer versions.

Here is an example of how to build a program from source.  This
example is for Autoconf; a similar approach should work for the other
developer prerequisites.  This example assumes Autoconf 2.71; it
should be OK to use a later version of Autoconf, if available.

  prefix=$HOME/prefix   # (or wherever else you choose)
  export PATH=$prefix/bin:$PATH
  wget https://ftp.gnu.org/pub/gnu/autoconf/autoconf-2.71.tar.gz
  gzip -d <autoconf-2.71.tar.gz | tar xf -
  cd autoconf-2.71
  ./configure --prefix=$prefix
  make install

Once the prerequisites are installed, you can build this package as
described in README-hacking.

Here are most of the steps we (maintainers) follow when making a release.

* start from a clean, up-to-date git directory.

    git checkout master; git pull

* Run ./configure && make maintainer-clean

* Ensure that the desired versions of autoconf, automake, bison, etc.
  are in your PATH.  See the buildreq list in bootstrap.conf for
  the complete list.

* Ensure that you're on "master" with no uncommitted diffs.
  This should produce no output: git checkout master; git diff

* Ensure that you've pushed all changes that belong in the release
  and that the NixOS/Hydra autobuilder is reporting all is well:

      https://hydra.nixos.org/jobset/gnu/coreutils-master

* Run bootstrap one last time.  This downloads any new translations:

    ./bootstrap

FIXME: enable excluded programs like arch? to get their manual pages?

* Check for new file system types by running the following command on
  a system with the most recent kernel possible (e.g., Fedora rawhide):

    make src/fs-magic-compare

  Or download the latest header first like:

    kgit='https://git.kernel.org/cgit/linux/kernel/git'
    wget -q $kgit/torvalds/linux.git/plain/include/uapi/linux/magic.h \
      -O src/fs-latest-magic.h

  If it finds a new file system magic number, add it to src/stat.c.
  If it is a remote file system tag it as such.

  Note there may be some new file systems magic values not defined
  in that linux/magic.h file, which can be seen at:

    https://www.livegrep.com/search/linux\
    ?q=%23define+.*_SUPER_MAGIC+-file%3Amagic\.h


* Pre-release testing:

  Run the following on at least one SELinux-enabled (enforcing) and
  one non-SELinux system:

    n=$(( ($(nproc) + 1) / 2 ))
    sudo env PATH="$PATH" NON_ROOT_USERNAME=$USER \
      make -k -j$(nproc) check-root SUBDIRS=. \
      && make distcheck \
      && make -j$n check RUN_VERY_EXPENSIVE_TESTS=yes RUN_EXPENSIVE_TESTS=yes

  If testing on systems with a non standard default shell, spurious failures
  may occur.  Often there are other shells available, and you can select
  those by using for example, SHELL=bash in the commands above.

  Note that the use of -j$n tells make to use approximately half of the
  available processing units.  If you use -jN, for larger N, some of the
  expensive tests are likely to interfere with concurrent performance-measuring
  or timing-sensitive tests, resulting in spurious failures.

  If "make distcheck" doesn't run "make syntax-check" for you, then run
  it manually:

    make syntax-check

* To set the date, version number, and release type [stable/alpha/beta] on
  line 3 of NEWS, commit that, and tag the release; run:

    build-aux/do-release-commit-and-tag X.Y stable

* Run the following to create release tarballs.  Your choice selects the
  corresponding upload-to destination in the emitted gnupload command.
  The different destinations are specified in cfg.mk.  See the definitions
  of gnu_ftp_host-{alpha,beta,stable}.

    # "TYPE" must be stable, beta or alpha
    make TYPE

* Test the tarball.  copy it to a few odd-ball systems and ensure that
  it builds and passes all tests.

* While that's happening, write the release announcement that you will
  soon post.  Start with the template, $HOME/announce-coreutils-X.Y
  that was just created by that "make" command.

  For generating counts use:
   oldrel=$(cat .prev-version)
   printf "There have been %d commits by %d people %s\n" \
     $(($(git log --oneline v$oldrel.. | wc -l) - 3))    \
     $(git shortlog v$oldrel.. | grep "^[^ ]" | wc -l)   \
     "in the [X] weeks since $oldrel"

   git shortlog v$oldrel.. | sed -n 's/:$//p' |
   sed 's/^/  /' | column -c 70 | expand

Once all the builds and tests have passed,

* Run the gnupload command that was suggested by your "make stable" run above.

* Wait a few minutes (maybe up to 30?) and then use the release URLs to
  download all tarball/signature pairs and use gpg --verify to ensure
  that they're all valid.

* Push the NEWS-updating changes and the new tag:

    v=$(cat .prev-version)
    git push origin master tag v$v

* Announce it on Savannah first, so you can include the preferable
  savannah.org announcement link in the email message.

  From here:
    https://savannah.gnu.org/projects/coreutils/
  click on the "submit news", then write something like the following:
  (If there is no such button, then enable "News" for the project via
   the Main -> "Select Features" menu item, or via this link:
   https://savannah.gnu.org/project/admin/editgroupfeatures.php?group=coreutils)

    Subject: coreutils-X.Y released [stable]
    +verbatim+
    ...paste the announcement here...
    -verbatim-

  Then go here to approve it:
    https://savannah.gnu.org/news/approve.php?group=coreutils

* Send the announcement email message (signed with the release key)

* Approve the announcement here:
  https://lists.gnu.org/mailman/admindb/coreutils-announce

* After each non-alpha release, update the on-line manual accessible via

    https://www.gnu.org/software/coreutils/manual/

  by running this:

    build-aux/gnu-web-doc-update --mirror

#! /bin/bash
# Convert this package for use with valgrind.

# Copyright (C) 2002-2023 Free Software Foundation, Inc.

# 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 3 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.



# Convert Makefile.am files:
#  find tests -name check.mk | xargs grep -wl PATH |
#    xargs perl -pi -e 's,src(\$\(PATH_SEPARATOR\)),src/vg$1,'
# To restore:
#  find tests -name check.mk | xargs grep -wl PATH |
#    xargs perl -pi -e 's,src/vg,src,'
#
# Create this symlink for suppressions (this is no longer necessary,
# with Linux kernel 2.6.9 and valgrind-2.2.0):
# ln -s $PWD/.vg-suppressions /tmp/cu-vg


# Create src/vg:

coreutils=$(echo 'spy:;@echo $(all_programs) $(noinst_PROGRAMS)' |
            (cd src; make -f Makefile -f - spy | tr -s '\n ' '  '))
mkdir -p src/vg
pwd=`pwd`
srcdir=$pwd/src
_path='export PATH='$srcdir':${PATH#*:}'
pre='#!/bin/sh\n'"$_path"'\n'
n=15 # stack trace depth
log_fd=3 # One can redirect this to file like 3>vg.log
test -e /tmp/cu-vg && suppressions='--suppressions=/tmp/cu-vg'
vg="exec /usr/bin/valgrind $suppressions --log-fd=$log_fd \
--leak-check=yes --track-fds=yes --leak-check=full --num-callers=$n"
cat <<EOF > src/vg/gen
for i in $coreutils; do
  printf "$pre$vg -- \$i"' "\$@"\n' > \$i
  chmod a+x \$i
done
EOF
cd src/vg
. ./gen