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