libnx  v4.2.0
env.h
Go to the documentation of this file.
1 /**
2  * @file env.h
3  * @brief Homebrew environment definitions and utilities.
4  * @author plutoo
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../types.h"
9 #include "../services/acc.h"
10 
11 /// Structure representing an entry in the homebrew environment configuration.
12 typedef struct {
13  u32 Key; ///< Type of entry
14  u32 Flags; ///< Entry flags
15  u64 Value[2]; ///< Entry arguments (type-specific)
16 } ConfigEntry;
17 
18 /// Entry flags
19 enum {
20  EntryFlag_IsMandatory = BIT(0), ///< Specifies that the entry **must** be processed by the homebrew application.
21 };
22 
23 ///< Types of entry
24 enum {
25  EntryType_EndOfList=0, ///< Entry list terminator.
26  EntryType_MainThreadHandle=1, ///< Provides the handle to the main thread.
27  EntryType_NextLoadPath=2, ///< Provides a buffer containing information about the next homebrew application to load.
28  EntryType_OverrideHeap=3, ///< Provides heap override information.
29  EntryType_OverrideService=4, ///< Provides service override information.
30  EntryType_Argv=5, ///< Provides argv.
31  EntryType_SyscallAvailableHint=6, ///< Provides syscall availability hints.
32  EntryType_AppletType=7, ///< Provides APT applet type.
33  EntryType_AppletWorkaround=8, ///< Indicates that APT is broken and should not be used.
34  EntryType_Reserved9=9, ///< Unused/reserved entry type, formerly used by StdioSockets.
35  EntryType_ProcessHandle=10, ///< Provides the process handle.
36  EntryType_LastLoadResult=11, ///< Provides the last load result.
37  EntryType_RandomSeed=14, ///< Provides random data used to seed the pseudo-random number generator.
38  EntryType_UserIdStorage=15, ///< Provides persistent storage for the preselected user id.
39  EntryType_HosVersion=16, ///< Provides the currently running Horizon OS version.
40 };
41 
42 enum {
43  EnvAppletFlags_ApplicationOverride = BIT(0) ///< Use AppletType_Application instead of AppletType_SystemApplication.
44 };
45 
46 /// Loader return function.
47 typedef void NORETURN (*LoaderReturnFn)(int result_code);
48 
49 /**
50  * @brief Parses the homebrew loader environment block (internally called).
51  * @param ctx Reserved.
52  * @param main_thread Reserved.
53  * @param saved_lr Reserved.
54  */
55 void envSetup(void* ctx, Handle main_thread, LoaderReturnFn saved_lr);
56 
57 /// Returns information text about the loader, if present.
58 const char* envGetLoaderInfo(void);
59 /// Returns the size of the loader information text.
61 
62 /// Retrieves the handle to the main thread.
64 /// Returns true if the application is running as NSO, otherwise NRO.
65 bool envIsNso(void);
66 
67 /// Returns true if the environment has a heap override.
68 bool envHasHeapOverride(void);
69 /// Returns the address of the overriden heap.
70 void* envGetHeapOverrideAddr(void);
71 /// Returns the size of the overriden heap.
73 
74 /// Returns true if the environment has an argv array.
75 bool envHasArgv(void);
76 /// Returns the pointer to the argv array.
77 void* envGetArgv(void);
78 
79 /**
80  * @brief Returns whether a syscall is hinted to be available.
81  * @param svc Syscall number to test.
82  * @returns true if the syscall is available.
83  */
84 bool envIsSyscallHinted(u8 svc);
85 
86 /// Returns the handle to the running homebrew process.
88 
89 /// Returns the loader's return function, to be called on program exit.
91 
92 /// Sets the return function to be called on program exit.
94 
95 /**
96  * @brief Configures the next homebrew application to load.
97  * @param path Path to the next homebrew application to load (.nro).
98  * @param argv Argument string to pass.
99  */
100 Result envSetNextLoad(const char* path, const char* argv);
101 
102 /// Returns true if the environment supports envSetNextLoad.
103 bool envHasNextLoad(void);
104 
105 /// Returns the Result from the last NRO.
107 
108 /// Returns true if the environment provides a random seed.
109 bool envHasRandomSeed(void);
110 
111 /**
112  * @brief Retrieves the random seed provided by the environment.
113  * @param out Pointer to a u64[2] buffer which will contain the random seed on return.
114  */
115 void envGetRandomSeed(u64 out[2]);
116 
117 /// Returns a pointer to the user id storage area (if present).
envGetRandomSeed
void envGetRandomSeed(u64 out[2])
Retrieves the random seed provided by the environment.
envGetLastLoadResult
Result envGetLastLoadResult(void)
Returns the Result from the last NRO.
EnvAppletFlags_ApplicationOverride
@ EnvAppletFlags_ApplicationOverride
Use AppletType_Application instead of AppletType_SystemApplication.
Definition: env.h:43
LoaderReturnFn
void(* LoaderReturnFn)(int result_code)
Loader return function.
Definition: env.h:47
EntryType_OverrideService
@ EntryType_OverrideService
Provides service override information.
Definition: env.h:29
envGetLoaderInfoSize
u64 envGetLoaderInfoSize(void)
Returns the size of the loader information text.
envGetUserIdStorage
AccountUid * envGetUserIdStorage(void)
Returns a pointer to the user id storage area (if present).
EntryType_EndOfList
@ EntryType_EndOfList
Entry list terminator.
Definition: env.h:25
envHasRandomSeed
bool envHasRandomSeed(void)
Returns true if the environment provides a random seed.
u8
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
envIsNso
bool envIsNso(void)
Returns true if the application is running as NSO, otherwise NRO.
envHasArgv
bool envHasArgv(void)
Returns true if the environment has an argv array.
envGetLoaderInfo
const char * envGetLoaderInfo(void)
Returns information text about the loader, if present.
ConfigEntry::Key
u32 Key
Type of entry.
Definition: env.h:13
AccountUid
Account UserId.
Definition: acc.h:25
envGetExitFuncPtr
LoaderReturnFn envGetExitFuncPtr(void)
Returns the loader's return function, to be called on program exit.
EntryType_NextLoadPath
@ EntryType_NextLoadPath
Provides a buffer containing information about the next homebrew application to load.
Definition: env.h:27
EntryType_AppletWorkaround
@ EntryType_AppletWorkaround
Indicates that APT is broken and should not be used.
Definition: env.h:33
EntryType_LastLoadResult
@ EntryType_LastLoadResult
Provides the last load result.
Definition: env.h:36
ConfigEntry::Flags
u32 Flags
Entry flags.
Definition: env.h:14
envIsSyscallHinted
bool envIsSyscallHinted(u8 svc)
Returns whether a syscall is hinted to be available.
u32
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21
envGetHeapOverrideSize
u64 envGetHeapOverrideSize(void)
Returns the size of the overriden heap.
EntryType_AppletType
@ EntryType_AppletType
Provides APT applet type.
Definition: env.h:32
EntryFlag_IsMandatory
@ EntryFlag_IsMandatory
Specifies that the entry must be processed by the homebrew application.
Definition: env.h:20
EntryType_RandomSeed
@ EntryType_RandomSeed
Provides random data used to seed the pseudo-random number generator.
Definition: env.h:37
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
Result
u32 Result
Function error code result type.
Definition: types.h:44
envSetup
void envSetup(void *ctx, Handle main_thread, LoaderReturnFn saved_lr)
Parses the homebrew loader environment block (internally called).
EntryType_MainThreadHandle
@ EntryType_MainThreadHandle
Provides the handle to the main thread.
Definition: env.h:26
EntryType_ProcessHandle
@ EntryType_ProcessHandle
Provides the process handle.
Definition: env.h:35
envGetArgv
void * envGetArgv(void)
Returns the pointer to the argv array.
envHasHeapOverride
bool envHasHeapOverride(void)
Returns true if the environment has a heap override.
envGetHeapOverrideAddr
void * envGetHeapOverrideAddr(void)
Returns the address of the overriden heap.
envHasNextLoad
bool envHasNextLoad(void)
Returns true if the environment supports envSetNextLoad.
ConfigEntry
Structure representing an entry in the homebrew environment configuration.
Definition: env.h:12
envSetNextLoad
Result envSetNextLoad(const char *path, const char *argv)
Configures the next homebrew application to load.
BIT
#define BIT(n)
Creates a bitmask from a bit number.
Definition: types.h:54
envGetOwnProcessHandle
Handle envGetOwnProcessHandle(void)
Returns the handle to the running homebrew process.
NORETURN
#define NORETURN
Marks a function as not returning, for the purposes of compiler optimization.
Definition: types.h:64
envSetExitFuncPtr
void envSetExitFuncPtr(LoaderReturnFn addr)
Sets the return function to be called on program exit.
EntryType_Reserved9
@ EntryType_Reserved9
Unused/reserved entry type, formerly used by StdioSockets.
Definition: env.h:34
EntryType_Argv
@ EntryType_Argv
Provides argv.
Definition: env.h:30
EntryType_OverrideHeap
@ EntryType_OverrideHeap
Provides heap override information.
Definition: env.h:28
envGetMainThreadHandle
Handle envGetMainThreadHandle(void)
Retrieves the handle to the main thread.
EntryType_HosVersion
@ EntryType_HosVersion
Provides the currently running Horizon OS version.
Definition: env.h:39
EntryType_UserIdStorage
@ EntryType_UserIdStorage
Provides persistent storage for the preselected user id.
Definition: env.h:38
Handle
u32 Handle
Kernel object handle.
Definition: types.h:43
EntryType_SyscallAvailableHint
@ EntryType_SyscallAvailableHint
Provides syscall availability hints.
Definition: env.h:31