docs/user/support/Architecture.dox

   1 /*
   2  * Copyright 2013-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Documentation by:
   6  *              John Scipione, jscipione@gmail.com
   7  *              Ingo Weinhold, ingo_weinhold@gmx.de
   8  *
   9  * Corresponds to:
  10  *              headers/os/support/Architecture.h        hrev47419
  11  *              src/kits/support/Architecture.cpp        hrev47419
  12  */
  13
  14
  15 /*!
  16         \file Architecture.h
  17         \ingroup support
  18         \ingroup libbe
  19         \brief Provides functions for getting the primary and secondary
  20                architectures of the system.
  21 */
  22
  23
  24 /*!
  25         \fn const char* get_architecture()
  26         \brief Returns the name of the caller's architecture.
  27
  28         This is the packaging architecture the caller's code has been built for,
  29         which may not be the system's primary architecture.
  30
  31         \return The name of the caller's architecture.
  32
  33         \see get_primary_architecture()
  34
  35         \since Haiku R1
  36 */
  37
  38
  39 /*!
  40         \fn const char* get_primary_architecture()
  41         \brief Returns the name of the system's primary architecture.
  42
  43         This is the packaging architecture the main system has been built for.
  44
  45         \return The name of the system's primary architecture.
  46
  47         \since Haiku R1
  48 */
  49
  50
  51 /*!
  52         \fn size_t get_secondary_architectures(const char** architectures,
  53                 size_t count)
  54         \brief Returns the names of the system's secondary architectures.
  55
  56         These are the packaging architectures the system does provide additional
  57         support for (i.e. not including the primary architecture). Only actually
  58         installed support is considered. E.g. on a pure x86 gcc 2 system
  59         (primary architecture "x86_gcc2") without any support installed for gcc 4
  60         executables, the function will not return any secondary architectures, even
  61         if it would be possible to install the support for gcc 4.
  62
  63         \param architectures A pre-allocated array of size \a count where the names
  64                of the secondary architectures will be stored. Can be \c NULL, if
  65                \a count is 0.
  66         \param count The size of the \a architectures array.
  67
  68         \return The actual number of secondary architectures. May be greater than
  69                 \a count, but at most \a count names will be written to
  70                 \a architectures.
  71
  72         \since Haiku R1
  73 */
  74
  75
  76 /*!
  77         \fn status_t get_secondary_architectures(BStringList& _architectures)
  78         \brief Returns the names of the system's secondary architectures.
  79
  80         This is a C++ interface similar to
  81         get_secondary_architectures(const char**,size_t). Instead of returning the
  82         architecture names in a pre-allocated array, it expects a BStringList.
  83         Note that this version can fail when running out of memory.
  84
  85         \param _architectures Reference to a BStringList that will be set to the
  86                list of names of secondary architectures. On error the list will be
  87                emptied.
  88
  89         \return A status code.
  90         \retval B_OK Everything went fine.
  91         \retval B_NO_MEMORY A memory allocation failed.
  92
  93         \see get_secondary_architectures(const char**,size_t)
  94
  95         \since Haiku R1
  96 */
  97
  98
  99 /*!
 100         \fn size_t get_architectures(const char** architectures,
 101                 size_t count)
 102         \brief Returns the names of the system's primary and secondary
 103                architectures.
 104
 105         This is a convenience function that returns both the primary architecture
 106         as returned by get_primary_architecture() and the secondary architectures
 107         as returned by get_secondary_architectures() in the provided array.
 108
 109         \param architectures A pre-allocated array of size \a count where the names
 110                of the architectures will be stored. Can be \c NULL if \a count is 0.
 111         \param count The size of the \a architectures array.
 112         \return The actual number of architectures. May be greater than \a count,
 113                 but at most \a count names will be written to \a architectures.
 114 */
 115
 116
 117 /*!
 118         \fn status_t get_architectures(BStringList& _architectures)
 119         \brief Returns the names of the system's primary and secondary
 120                architectures.
 121
 122         This is a C++ interface similar to
 123         get_architectures(const char**,size_t). Instead of returning the
 124         architecture names in a pre-allocated array, it expects a BStringList.
 125         Note that this version can fail when running out of memory.
 126
 127         \param _architectures Reference to a BStringList that will be set to the
 128                list of names of primary and secondary architectures. On error the
 129                list will be emptied.
 130
 131         \return A status code.
 132         \retval B_OK Everything went fine.
 133         \retval B_NO_MEMORY A memory allocation failed.
 134
 135         \see get_architectures(const char**,size_t)
 136
 137         \since Haiku R1
 138 */
 139
 140
 141 /*!
 142         \fn const char* guess_architecture_for_path(const char* path)
 143         \brief Returns the name of the architecture associated with the given path.
 144
 145         If the given path refers to an executable, library, or add-on, the function
 146         determines for which architecture it has been built and returns that.
 147         Otherwise it analyzes the path itself, checking whether it points to/into a
 148         directory where files for a secondary architectures reside. If that proved
 149         inconclusive the name of the primary architecture is returned.
 150
 151         \param path The path to be analyzed. It doesn't necessarily have to point to
 152                an existing file or directory.
 153
 154         \return The name of the architecture determined from \a path.
 155
 156         \since Haiku R1
 157 */