gprofng/doc/gp-archive.texi - third_party/binutils-gdb - Git at Google

 @c ----------------------------------------------------------------------------
 @c This is the Texinfo source file for the gp-archive man page.
 @c
 @c Author: Ruud van der Pas
 @c ----------------------------------------------------------------------------
 @ifset man
 \input texinfo @c -*-texinfo-*-
 @setfilename gp-archive
 @settitle Archive gprofng experiment data
 @include gp-macros.texi
 @end ifset

 @c ----------------------------------------------------------------------------
 @c This is from the man-pages(7) man page
 @c
 @c "The list below shows conventional or suggested sections.  Most manual pages
 @c  should include at least the highlighted sections.  Arrange a new manual
 @c  page so that sections are placed in the order shown in the list."
 @c
 @c              NAME
 @c              SYNOPSIS
 @c              CONFIGURATION    [Normally only in Section 4]
 @c              DESCRIPTION
 @c              OPTIONS          [Normally only in Sections 1, 8]
 @c              EXIT STATUS      [Normally only in Sections 1, 8]
 @c              RETURN VALUE     [Normally only in Sections 2, 3]
 @c              ERRORS           [Typically only in Sections 2, 3]
 @c              ENVIRONMENT
 @c              FILES
 @c              VERSIONS         [Normally only in Sections 2, 3]
 @c              ATTRIBUTES       [Normally only in Sections 2, 3]
 @c              CONFORMING TO
 @c              NOTES
 @c              BUGS
 @c              EXAMPLES
 @c              AUTHORS          [Discouraged]
 @c              REPORTING BUGS   [Not used in man-pages]
 @c              COPYRIGHT        [Not used in man-pages]
 @c              SEE ALSO
 @c
 @c This is what the texi2pod.pl tool recognizes:
 @c
 @c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
 @c               BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
 @c
 @c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
 @c makes sense and adhered to for the other formats.
 @c ----------------------------------------------------------------------------

 @c ----------------------------------------------------------------------------
 @c NAME section
 @c ----------------------------------------------------------------------------

 @ManPageStart{NAME}
 @c man begin NAME

 gp-archive - Archive the associated application binaries and sources for a
 gprofng experiment

 @c man end
 @ManPageEnd{}

 @c ----------------------------------------------------------------------------
 @c SYNOPSIS section
 @c ----------------------------------------------------------------------------

 @ManPageStart{SYNOPSIS}
 @c man begin SYNOPSIS

 @command{gprofng archive} [@var{option(s)}] @var{experiment}

 @c man end
 @ManPageEnd{}

 @c ----------------------------------------------------------------------------
 @c DESCRIPTION section
 @c ----------------------------------------------------------------------------

 @ManPageStart{DESCRIPTION}
 @c man begin DESCRIPTION

 Archive the associated application binaries and source files in a gprofng
 experiment to make it self contained and portable.

 By default, the binaries are archived as part of the data collection, but the
 application source files are not archived.  Use this tool to change this and
 afterwards archive additional components.

 This tool has to be executed on the same system where the profiling data was
 recorded.

 @c man end
 @ManPageEnd{}

 @c ----------------------------------------------------------------------------
 @c OPTIONS section
 @c ----------------------------------------------------------------------------

 @ManPageStart{OPTIONS}
 @c man begin OPTIONS

 @table @gcctabopt

 @item --version
 @ifclear man
 @IndexSubentry{Options, @code{--version}}
 @end ifclear

 Print the version number and exit.

 @item --help
 @ifclear man
 @IndexSubentry{Options, @code{--help}}
 @end ifclear

 Print usage information and exit.

 @item -a @{off | on | ldobjects | src | usedldobjects | used[src]@}
 @ifclear man
 @IndexSubentry{Options, @code{-a}}
 @end ifclear

 Specify archiving of binaries and other files.  In addition to disable this
 feature (@samp{off}), or enable archiving of all loadobjects and sources
 (@samp{on}), the other choices support a more refined selection.

 All of these choices enable archiving, but the keyword controls what exactly
 is selected: all load objects (@samp{ldobjects}), all source files
 (@samp{src}), the loadobjects associated with a program counter
 (@samp{usedldobjects}), or the source files associated with a program counter
 (@samp{used[src]}).  The default is @samp{-a ldobjects}.

 @item -d @var{path}
 @ifclear man
 @IndexSubentry{Options, @code{-d}}
 @end ifclear

 The @var{path} is the absolute path to a common archive, which is a
 directory that contains archived files.  If the directory does not
 exist, then it will be created.  Files are saved in the common archive
 directory, and a symbolic link is created in the experiment archive.

 @item -F
 @ifclear man
 @IndexSubentry{Options, @code{-F}}
 @end ifclear

 Force writing, or rewriting of .archive files.  All archived files will be
 removed and recreated, except if the @samp{-n} or @samp{-m} option is used,
 or if the experiment is a subexperiment.

 @item -m @var{regex}
 @ifclear man
 @IndexSubentry{Options, @code{-m}}
 @end ifclear

 Archive only those source, object, and debug info files whose full path name
 matches the given POSIX compliant @var{regex} regular expression.

 @item -n
 @ifclear man
 @IndexSubentry{Options, @code{-n}}
 @end ifclear

 Archive the named experiment only, not any of its descendants.

 @item -q
 @ifclear man
 @IndexSubentry{Options, @code{-q}}
 @end ifclear

 Do not write any warnings to @file{stderr}.  Warnings are incorporated into
 the .archive file in the experiment directory.  They are shown in the output
 of the @command{gprofng display text} command.

 @item -r @var{path}
 @ifclear man
 @IndexSubentry{Options, @code{-r}}
 @end ifclear

 This option specifies the location of a common archive.  The value is the
 relative path to a common archive, which is a directory that contains
 archived files.
 If the directory does not exist, then it will be created.  Files are saved
 in the common archive directory, and a symbolic link is created in the
 experiment archive.

 @item -s @var{selection}
 @ifclear man
 @IndexSubentry{Options, @code{-s}}
 @end ifclear

 Specify archiving of source files.  The allowed values for @var{selection} are:

 @table @gcctabopt

 @item no

 Do not archive any source files.

 @item all

 Archive all source and object files that can be found.

 @item used[src]

 Archive source and object files for functions against which data was
 recorded in the experiment, and that can be found.
 @end table

 By default, application source files are not archived into the experiment.
 If the @samp{-s all}, or @samp{-s used} option is used, sources and object
 files are archived.
 These options also ensure that source files are available in the experiment,
 even if the original source files have been modified, or are inaccessible
 afterwards.

 In case archive files cannot be found, use the @samp{addpath}, or
 @samp{pathmap} command, or both, in an @file{.er.rc} file to specify the
 location of the missing file(s).

 @end table

 @c man end
 @ManPageEnd{}

 @c ----------------------------------------------------------------------------
 @c NOTES section
 @c ----------------------------------------------------------------------------

 @ManPageStart{NOTES}
 @c man begin NOTES

 @itemize @minus

 @c ----------------------------------------------------------------------------
 @item
 Archiving of application binaries -
 By default, binaries are archived automatically when an experiment is
 created.  However, archiving does not occur in one or more of the
 following circumstances:

 @itemize @bullet

 @item
 If the profiled application is terminated before it exits normally.

 @item
 If a running process is profiled.

 @item
 If archiving is explicitly disabled when profiling.  For example by using
 the @samp{-a off} option on @command{gprofng collect app}.

 @end itemize

 In these cases, @command{gprofng archive} must be run manually and on the same
 machine where the profiling data was recorded.

 Archiving of experiment data during the data collection process can be quite
 expensive.  Especially if the experiment has many descendant processes.
 @ifclear man
 @IndexSubentry{Options, @code{-a}}
 @end ifclear
 In such cases, a more efficient strategy is to use the @samp{-a off} option
 when collecting the data.  Once the collection has completed, the data can be
 @ifclear man
 @IndexSubentry{Options, @code{-s}}
 @end ifclear
 archived using the @samp{-s all} option.  This saves all executables and
 source files in the experiment.

 If during the archiving there is an error message that an executable, or
 @ifclear man
 @IndexSubentry{Commands, @code{addpath}}
 @end ifclear
 source file cannot be found, the @samp{addpath} command to add the path
 to the missing file(s) can be included in the @file{.er.rc} file.
 After this command has been added, archive the experiment again.  The
 archiving archiving can be repeated as many times as necessary to archive all
 files.

 Archiving should be done on the same system as was used to collect the
 experiment.  If some files cannot be accessed from this system (e.g.  sources
 or object files), then additional archiving can be done using another system
 that can access them.  For example, the system where the application was built.

 Some Java applications store shared objects in jar files.  By default, such
 shared objects are not automatically archived.  To archive shared objects
 contained in jar files, make sure to include the @samp{addpath} command in
 an @file{.er.rc} file.
 The @samp{addpath} command should give the path to the jar file, including
 the jar file itself.  The @file{.er.rc} file should be saved in the user home
 directory, or experiment parent directory.

 @item
 Archiving of application sources -
 By default, application source files are not archived in the experiment.
 Execute the @command{gprofng archive} command with the @samp{-s all}, or
 @samp{-s used} option on each experiment to store source files in the
 experiment.

 @item
 Automatic archiving of application sources -
 Environment variable @samp{GPROFNG_ARCHIVE} may be set to automatically
 archive sources when the experiment has completed.  This environment
 variable can contain @samp{-s} and @samp{-m} arguments, as pairs of
 argument and options, separated by one or more blanks.
 @ifclear man
 @IndexSubentry{Environment variables, @code{GPROFNG_ARCHIVE}}
 @IndexSubentry{Options, @code{-a}}
 @IndexSubentry{Options, @code{-m}}
 @IndexSubentry{Options, @code{-s}}
 @end ifclear

 If more than one @samp{-s} argument appears on the command line, the
 last one prevails.  If @samp{-s} is both passed on the command line, and
 set by the environment variable, the option from the environment variable
 prevails.

 Note that in case automatic source archiving during data collection has
 been enabled using either the @samp{GPROFNG_ARCHIVE} variable, or the
 @samp{-a src}, or @samp{-a usedsrc} option, it is recommended to confirm that
 source files have been correctly resolved by executing the
 @command{gprofng archive -s all}, or @command{gprofng archive -s used}
 command.

 @item
 The @samp{-d} and @samp{-r} options are mutually exclusive.
 @ifclear man
 @IndexSubentry{Options, @code{-d}}
 @IndexSubentry{Options, @code{-r}}
 @end ifclear

 @item
 When using the @samp{-d} or @samp{-r} option, environment variable
 @ifclear man
 @IndexSubentry{Options, @code{-d}}
 @IndexSubentry{Options, @code{-r}}
 @IndexSubentry{Environment variables, @code{GPROFNG_ARCHIVE_COMMON_DIR}}
 @end ifclear
 @samp{GPROFNG_ARCHIVE_COMMON_DIR} can be used to specify the location of
 the common archive.  This can be very convenient when using a script to
 profile applications.

 @item
 If more than one @samp{-s} option is given on the command line, or
 specified in the environment variable, the specified option for all must
 be the same.  If not, @command{gprofng archive} exits with an error.

 @item
 This tool does not work on experiments recorded with earlier versions of
 the tools.  If invoked on such experiments, a warning is printed.  Use the
 version of @command{gprofng archive} from the same release with which the
 experiment was recorded.

 @end itemize

 @c man end
 @ManPageEnd{}

 @c ----------------------------------------------------------------------------
 @c SEEALSO section
 @c ----------------------------------------------------------------------------

 @ManPageStart{SEE ALSO}
 @c man begin SEEALSO

 gprofng(1),
 gp-collect-app(1),
 gp-display-gui(1),
 gp-display-html(1),
 gp-display-src(1),
 gp-display-text(1)

 @iftex
 @vspace{1}
 @end iftex

 The user guide for gprofng is maintained as a Texinfo manual.  If the info
 and gprofng programs are correctly installed, the command
 @command{info gprofng} should give access to this document.

 @c man end
 @ManPageEnd{}

 @c ----------------------------------------------------------------------------
 @c COPYRIGHT section
 @c ----------------------------------------------------------------------------

 @ManPageStart{COPYRIGHT}
 @c man begin COPYRIGHT

 Copyright @copyright{} 2022-2024 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
 section entitled ``GNU Free Documentation License''.

 @c man end
 @ManPageEnd{}

 @c ----------------------------------------------------------------------------
 @c If this text is used for a man page, exit.  Otherwise we need to continue.
 @c ----------------------------------------------------------------------------

 @ifset man
 @bye
 @end ifset
	@c ----------------------------------------------------------------------------
	@c This is the Texinfo source file for the gp-archive man page.
	@c
	@c Author: Ruud van der Pas
	@c ----------------------------------------------------------------------------
	@ifset man
	\input texinfo @c --texinfo--
	@setfilename gp-archive
	@settitle Archive gprofng experiment data
	@include gp-macros.texi
	@end ifset

	@c ----------------------------------------------------------------------------
	@c This is from the man-pages(7) man page
	@c
	@c "The list below shows conventional or suggested sections. Most manual pages
	@c should include at least the highlighted sections. Arrange a new manual
	@c page so that sections are placed in the order shown in the list."
	@c
	@c NAME
	@c SYNOPSIS
	@c CONFIGURATION [Normally only in Section 4]
	@c DESCRIPTION
	@c OPTIONS [Normally only in Sections 1, 8]
	@c EXIT STATUS [Normally only in Sections 1, 8]
	@c RETURN VALUE [Normally only in Sections 2, 3]
	@c ERRORS [Typically only in Sections 2, 3]
	@c ENVIRONMENT
	@c FILES
	@c VERSIONS [Normally only in Sections 2, 3]
	@c ATTRIBUTES [Normally only in Sections 2, 3]
	@c CONFORMING TO
	@c NOTES
	@c BUGS
	@c EXAMPLES
	@c AUTHORS [Discouraged]
	@c REPORTING BUGS [Not used in man-pages]
	@c COPYRIGHT [Not used in man-pages]
	@c SEE ALSO
	@c
	@c This is what the texi2pod.pl tool recognizes:
	@c
	@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
	@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
	@c
	@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
	@c makes sense and adhered to for the other formats.
	@c ----------------------------------------------------------------------------

	@c ----------------------------------------------------------------------------
	@c NAME section
	@c ----------------------------------------------------------------------------

	@ManPageStart{NAME}
	@c man begin NAME

	gp-archive - Archive the associated application binaries and sources for a
	gprofng experiment

	@c man end
	@ManPageEnd{}

	@c ----------------------------------------------------------------------------
	@c SYNOPSIS section
	@c ----------------------------------------------------------------------------

	@ManPageStart{SYNOPSIS}
	@c man begin SYNOPSIS

	@command{gprofng archive} [@var{option(s)}] @var{experiment}

	@c man end
	@ManPageEnd{}

	@c ----------------------------------------------------------------------------
	@c DESCRIPTION section
	@c ----------------------------------------------------------------------------

	@ManPageStart{DESCRIPTION}
	@c man begin DESCRIPTION

	Archive the associated application binaries and source files in a gprofng
	experiment to make it self contained and portable.

	By default, the binaries are archived as part of the data collection, but the
	application source files are not archived. Use this tool to change this and
	afterwards archive additional components.

	This tool has to be executed on the same system where the profiling data was
	recorded.

	@c man end
	@ManPageEnd{}

	@c ----------------------------------------------------------------------------
	@c OPTIONS section
	@c ----------------------------------------------------------------------------

	@ManPageStart{OPTIONS}
	@c man begin OPTIONS

	@table @gcctabopt

	@item --version
	@ifclear man
	@IndexSubentry{Options, @code{--version}}
	@end ifclear

	Print the version number and exit.

	@item --help
	@ifclear man
	@IndexSubentry{Options, @code{--help}}
	@end ifclear

	Print usage information and exit.

	@item -a @{off \| on \| ldobjects \| src \| usedldobjects \| used[src]@}
	@ifclear man
	@IndexSubentry{Options, @code{-a}}
	@end ifclear

	Specify archiving of binaries and other files. In addition to disable this
	feature (@samp{off}), or enable archiving of all loadobjects and sources
	(@samp{on}), the other choices support a more refined selection.

	All of these choices enable archiving, but the keyword controls what exactly
	is selected: all load objects (@samp{ldobjects}), all source files
	(@samp{src}), the loadobjects associated with a program counter
	(@samp{usedldobjects}), or the source files associated with a program counter
	(@samp{used[src]}). The default is @samp{-a ldobjects}.

	@item -d @var{path}
	@ifclear man
	@IndexSubentry{Options, @code{-d}}
	@end ifclear

	The @var{path} is the absolute path to a common archive, which is a
	directory that contains archived files. If the directory does not
	exist, then it will be created. Files are saved in the common archive
	directory, and a symbolic link is created in the experiment archive.

	@item -F
	@ifclear man
	@IndexSubentry{Options, @code{-F}}
	@end ifclear

	Force writing, or rewriting of .archive files. All archived files will be
	removed and recreated, except if the @samp{-n} or @samp{-m} option is used,
	or if the experiment is a subexperiment.

	@item -m @var{regex}
	@ifclear man
	@IndexSubentry{Options, @code{-m}}
	@end ifclear

	Archive only those source, object, and debug info files whose full path name
	matches the given POSIX compliant @var{regex} regular expression.

	@item -n
	@ifclear man
	@IndexSubentry{Options, @code{-n}}
	@end ifclear

	Archive the named experiment only, not any of its descendants.

	@item -q
	@ifclear man
	@IndexSubentry{Options, @code{-q}}
	@end ifclear

	Do not write any warnings to @file{stderr}. Warnings are incorporated into
	the .archive file in the experiment directory. They are shown in the output
	of the @command{gprofng display text} command.

	@item -r @var{path}
	@ifclear man
	@IndexSubentry{Options, @code{-r}}
	@end ifclear

	This option specifies the location of a common archive. The value is the
	relative path to a common archive, which is a directory that contains
	archived files.
	If the directory does not exist, then it will be created. Files are saved
	in the common archive directory, and a symbolic link is created in the
	experiment archive.

	@item -s @var{selection}
	@ifclear man
	@IndexSubentry{Options, @code{-s}}
	@end ifclear

	Specify archiving of source files. The allowed values for @var{selection} are:

	@table @gcctabopt

	@item no

	Do not archive any source files.

	@item all

	Archive all source and object files that can be found.

	@item used[src]

	Archive source and object files for functions against which data was
	recorded in the experiment, and that can be found.
	@end table

	By default, application source files are not archived into the experiment.
	If the @samp{-s all}, or @samp{-s used} option is used, sources and object
	files are archived.
	These options also ensure that source files are available in the experiment,
	even if the original source files have been modified, or are inaccessible
	afterwards.

	In case archive files cannot be found, use the @samp{addpath}, or
	@samp{pathmap} command, or both, in an @file{.er.rc} file to specify the
	location of the missing file(s).

	@end table

	@c man end
	@ManPageEnd{}

	@c ----------------------------------------------------------------------------
	@c NOTES section
	@c ----------------------------------------------------------------------------

	@ManPageStart{NOTES}
	@c man begin NOTES

	@itemize @minus

	@c ----------------------------------------------------------------------------
	@item
	Archiving of application binaries -
	By default, binaries are archived automatically when an experiment is
	created. However, archiving does not occur in one or more of the
	following circumstances:

	@itemize @bullet

	@item
	If the profiled application is terminated before it exits normally.

	@item
	If a running process is profiled.

	@item
	If archiving is explicitly disabled when profiling. For example by using
	the @samp{-a off} option on @command{gprofng collect app}.

	@end itemize

	In these cases, @command{gprofng archive} must be run manually and on the same
	machine where the profiling data was recorded.

	Archiving of experiment data during the data collection process can be quite
	expensive. Especially if the experiment has many descendant processes.
	@ifclear man
	@IndexSubentry{Options, @code{-a}}
	@end ifclear
	In such cases, a more efficient strategy is to use the @samp{-a off} option
	when collecting the data. Once the collection has completed, the data can be
	@ifclear man
	@IndexSubentry{Options, @code{-s}}
	@end ifclear
	archived using the @samp{-s all} option. This saves all executables and
	source files in the experiment.

	If during the archiving there is an error message that an executable, or
	@ifclear man
	@IndexSubentry{Commands, @code{addpath}}
	@end ifclear
	source file cannot be found, the @samp{addpath} command to add the path
	to the missing file(s) can be included in the @file{.er.rc} file.
	After this command has been added, archive the experiment again. The
	archiving archiving can be repeated as many times as necessary to archive all
	files.

	Archiving should be done on the same system as was used to collect the
	experiment. If some files cannot be accessed from this system (e.g. sources
	or object files), then additional archiving can be done using another system
	that can access them. For example, the system where the application was built.

	Some Java applications store shared objects in jar files. By default, such
	shared objects are not automatically archived. To archive shared objects
	contained in jar files, make sure to include the @samp{addpath} command in
	an @file{.er.rc} file.
	The @samp{addpath} command should give the path to the jar file, including
	the jar file itself. The @file{.er.rc} file should be saved in the user home
	directory, or experiment parent directory.

	@item
	Archiving of application sources -
	By default, application source files are not archived in the experiment.
	Execute the @command{gprofng archive} command with the @samp{-s all}, or
	@samp{-s used} option on each experiment to store source files in the
	experiment.

	@item
	Automatic archiving of application sources -
	Environment variable @samp{GPROFNG_ARCHIVE} may be set to automatically
	archive sources when the experiment has completed. This environment
	variable can contain @samp{-s} and @samp{-m} arguments, as pairs of
	argument and options, separated by one or more blanks.
	@ifclear man
	@IndexSubentry{Environment variables, @code{GPROFNG_ARCHIVE}}
	@IndexSubentry{Options, @code{-a}}
	@IndexSubentry{Options, @code{-m}}
	@IndexSubentry{Options, @code{-s}}
	@end ifclear

	If more than one @samp{-s} argument appears on the command line, the
	last one prevails. If @samp{-s} is both passed on the command line, and
	set by the environment variable, the option from the environment variable
	prevails.

	Note that in case automatic source archiving during data collection has
	been enabled using either the @samp{GPROFNG_ARCHIVE} variable, or the
	@samp{-a src}, or @samp{-a usedsrc} option, it is recommended to confirm that
	source files have been correctly resolved by executing the
	@command{gprofng archive -s all}, or @command{gprofng archive -s used}
	command.

	@item
	The @samp{-d} and @samp{-r} options are mutually exclusive.
	@ifclear man
	@IndexSubentry{Options, @code{-d}}
	@IndexSubentry{Options, @code{-r}}
	@end ifclear

	@item
	When using the @samp{-d} or @samp{-r} option, environment variable
	@ifclear man
	@IndexSubentry{Options, @code{-d}}
	@IndexSubentry{Options, @code{-r}}
	@IndexSubentry{Environment variables, @code{GPROFNG_ARCHIVE_COMMON_DIR}}
	@end ifclear
	@samp{GPROFNG_ARCHIVE_COMMON_DIR} can be used to specify the location of
	the common archive. This can be very convenient when using a script to
	profile applications.

	@item
	If more than one @samp{-s} option is given on the command line, or
	specified in the environment variable, the specified option for all must
	be the same. If not, @command{gprofng archive} exits with an error.

	@item
	This tool does not work on experiments recorded with earlier versions of
	the tools. If invoked on such experiments, a warning is printed. Use the
	version of @command{gprofng archive} from the same release with which the
	experiment was recorded.

	@end itemize

	@c man end
	@ManPageEnd{}

	@c ----------------------------------------------------------------------------
	@c SEEALSO section
	@c ----------------------------------------------------------------------------

	@ManPageStart{SEE ALSO}
	@c man begin SEEALSO

	gprofng(1),
	gp-collect-app(1),
	gp-display-gui(1),
	gp-display-html(1),
	gp-display-src(1),
	gp-display-text(1)

	@iftex
	@vspace{1}
	@end iftex

	The user guide for gprofng is maintained as a Texinfo manual. If the info
	and gprofng programs are correctly installed, the command
	@command{info gprofng} should give access to this document.

	@c man end
	@ManPageEnd{}

	@c ----------------------------------------------------------------------------
	@c COPYRIGHT section
	@c ----------------------------------------------------------------------------

	@ManPageStart{COPYRIGHT}
	@c man begin COPYRIGHT

	Copyright @copyright{} 2022-2024 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
	section entitled ``GNU Free Documentation License''.

	@c man end
	@ManPageEnd{}

	@c ----------------------------------------------------------------------------
	@c If this text is used for a man page, exit. Otherwise we need to continue.
	@c ----------------------------------------------------------------------------

	@ifset man
	@bye
	@end ifset