================
Binary Utilities
================

.. default-domain:: bash

.. file:: bin_utils.bsh

:Functions: - object_bits - Print out the number of bits in an object file (requires nm)
:Parameters: --bits - Call :func:`object_bits` with on ``$2``
:Output: *stdout* - number of bits in object file

A collection of binary utilities

This file can be sourced to load the functions, or executed for a one time call.

.. function:: object_bits

:Parameters: ``$1`` - Filename (.o, .a, .so, executable, etc...)
:Output: *stdout* - Prints the number of bits
:Uses: * ``nm`` - Most OSes have this installed already. Sometimes a binutils package needs to be installed to get this.
       * ``lipo`` - On macOS, uses ``lipo`` instead of ``nm``.

Prints out the number of bits (typically 32 or 64) in a file

.. note::

   On macOS, it is common to have both 32 and 64 printed out. I.e. ``32 64``

.. function:: lwhich

:Parameters: * ``$1`` - The number of bits in the architecture to match
             * ``$2`` - The library to search for. Must match the beginning of the the basename of the library, but may also contain extended (grep) regex.
             * [``LWHICH_INSENSITIVE``] - Enables case insensitivity. Default: ``0`` (case sensitive)
:Output: matches - Full path array of matching filenames

.. rubric:: Example

.. code-block:: bash

   lwhich 64 libSDL
   lwhich 32 'libc\.so'
   lwhich 64 '(libSDL|libOpenGL)'

:Uses: ``nm`` - Most OSes have this installed already. Sometimes a binutils package needs to be installed to get this

which for shared libraries

Searches for a library using the same ld resolution method as the OS. First ``LD_LIBRARY_PATH`` is searched, then ldconfig -p for a match to a filename.

.. rubric:: Bugs

Since macOS integrity checker blocks the ability to export ``LD_LIBRARY_PATH`` and ``DYLD_LIBRARY_PATH``, ``MACLD_LIBRARY_PATH`` can be used instead.

.. rubric:: Bugs

The purpose of this is to match from the beginning of basename (cf. the full pathname). This is done by using ``$2`` as a partial regex which can cause some undesired behavior. This can occur when using the or '|' operator. This is why the example has parentheses in the '(libSDL|libOpenGL)' expression, so that it works as expected.

This behavior can be taken advantage of by using the or '|' operator without parentheses to do an partial path search.

    lwhich 64 '$|local'

The $ will short-circuit the normal lwhich behavior, and now matches any path containing local, for example all the libraries in /usr/local/lib

Or to find any library with the word linux in the basename:

    lwhich 32 '$|linux[^/]*\.so'

(This will find common libraries such as ld-linux.so and libselinux.so)