=pod

=head1 NAME

valgrind-tests - How we test for valgrind

=head1 DESCRIPTION

We have CI jobs that run to verify that the suppression file we
ship with valgrind functions correctly when users use valgrind
with full leak checking.

While doing full leak checking shows the global objects the library
frees on exit as leaks, which really are not leaks, it is a chore
to continuously tell people to ignore the results from the library.

==head1 ENVIRONMENT

Normally the openssl application main program and the test main program
always call OPENSSL_cleanup(). This means that running these applications
under valgrind will not show anything. Therefore we selectively disable
the call to OPENSSL_cleanup() when running these applications for
testing.

the test environment sets the environment variable

I<OSSL_USE_VALGRIND> when using valgrind to run our tests.

As such the main programs above are instrumented so that when they
are built and the <valgrind/valgrind.h> header can be seen in the
include path, the macro RUNNING_ON_VALGRIND is used at exit time
to test to see if the program is actually running under valgrind.

If the program is running under valgrind, the program checks to
see if I<OSSL_USE_VALGRIND> is set in the environment. If so,
the call to OPENSSL_cleanup() is skipped on exit. This will ensure
the library globals are noticed by valgrind with full leak checking
ensuring our suppression file is working in CI.

=head1 COPYRIGHT

Copyright 2026 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut
