.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
.\"
.Dd December 07, 2020
.Dt ctfconvert 1ONBLD
.Os
.Sh NAME
.Nm ctfconvert
.Nd Convert ELF object debug data to CTF container
.Sh SYNOPSIS
.Nm
.Op Fl fikms
.Op Fl b Ar batchsize
.Op Fl j Ar threads
.Op Fl l Ar label | Fl L Ar labelenv
.Op Fl M Ar ignorefile
.Op Fl o Ar outfile
.Ar ELF_object
.Sh DESCRIPTION
The
.Nm
utility converts debug information found within
.Ar ELF_object
to CTF data and adds this to a CTF container.
.Ar ELF_object
can be a single object file or a fully linked object such as a shared library
or binary.
.Nm
currently supports input debug data in DWARFv2 or DWARFv4 format.
Unless the
.Fl o
option is present, this is done in-place; the original file being modified
with a new CTF container being added.
For in-place processing, unless the
.Fl k
option is present, the source file will be removed if an error occurs.
.Sh OPTIONS
The following options are supported:
.Bl -tag -width Ar
.It Fl f
Always attempt conversion.
This option causes
.Nm
to attempt conversion even for files where it does not seem appropriate.
This is occasionally necessary to convert objects which have had some
local symbols removed from the symbol table.
.It Fl i
Ignore files not built partially from C sources.
.Nm
will usually check
.Ar ELF_object
to see if at least one of the input files was a
.Sq .c
file, and exit with an error if not.
With the
.Fl i
option, the check is still done but
.Nm
will exit with a success status instead of an error.
In either case, conversion is not attempted.
To attempt conversion even when the object does not appear to have been built
from C sources, use the
.Fl f
option.
.It Fl k
When processing a file in-place and an error occurs, keep the input file
rather than deleting it.
.It Fl m
Allow
.Ar ELF_object
to have missing debug data.
By default,
.Nm
requires that each C source compilation unit in
.Ar ELF_object
contains debug data, and will exit with an error if this is not the case.
The
.Fl m
option relaxes this restriction allowing processing of such files.
Note that if the file contains no debug data in any of the compilation units
then this flag will cause
.Nm
to exit successfully without taking any action, and can mask missing debug data.
.It Fl M Ar ignorefile
Allow
.Ar ELF_object
to have missing debug data in selected source files.
The source files to ignore are specified as a list of file basenames (without
any directory component) in
.Ar ignorefile .
Each file should be listed on its own line, separated by a newline.
It is not possible to encode a file name that contains a newline and any other
white-space within the line is considered to be part of the file name being
specified.
The
.Sq /
character may not appear in the file name.
Empty lines and any line which has a
.Sq #
character in the first column are ignored.
.It Fl b Ar batchsize
Batch-process this many compilation units from the source file at once (default
256). This helps to reduce memory usage when processing large objects which
were built from many source files.
.It Fl j Ar threads
Use this many threads to perform the merge (default 4).
.It Fl l Ar label
Set the output container's label to the specified value.
.It Fl L Ar labelenv
Set the output container's label to the value of the specified environment
variable.
.It Fl o Ar outfile
Write the new object with added CTF ta to the specified output file, rather
than updating the input in-place.
.It Fl s
This option allows truncation of data that cannot be converted to CTF format
because it exceeds the allowed size.
Without this option being provided, conversion of such data would produce a
fatal error.
The current implementation allows truncation of
.Vt enum
definitions.
When this occurs the resulting CTF data does not contain all possible
.Vt enum
values and a warning will be produced for each truncation.
.El
.Sh OPERANDS
The following operands are supported:
.Bl -tag -width Ar
.It Ar object_file
The source object file to process.
.El
.Sh EXIT STATUS
.Bl -inset
.It Sy 0
.Dl Execution completed successfully.
.It Sy 1
.Dl A fatal error occurred.
.It Sy 2
.Dl Invalid command line options were specified.
.El
.Sh INTERFACE STABILITY
The command line interface of
.Nm
is
.Sy Uncommitted .
The output of
.Nm
is
.Sy Not-An-Interface
and may change at any time.
.Sh SEE ALSO
.Xr ctfdiff 1 ,
.Xr ctfdump 1 ,
.Xr ctf 4