1 /** 2 * \file wasi.h 3 * 4 * C API for WASI 5 */ 6 7 #ifndef WASI_H 8 #define WASI_H 9 10 #include "wasm.h" 11 #include <stdint.h> 12 13 #ifndef WASI_API_EXTERN 14 #ifdef _WIN32 15 #define WASI_API_EXTERN __declspec(dllimport) 16 #else 17 #define WASI_API_EXTERN 18 #endif 19 #endif 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 #define own 26 27 #define WASI_DECLARE_OWN(name) \ 28 typedef struct wasi_##name##_t wasi_##name##_t; \ 29 WASI_API_EXTERN void wasi_##name##_delete(own wasi_##name##_t *); 30 31 /** 32 * \typedef wasi_config_t 33 * \brief Convenience alias for #wasi_config_t 34 * 35 * \struct wasi_config_t 36 * \brief TODO 37 * 38 * \fn void wasi_config_delete(wasi_config_t *); 39 * \brief Deletes a configuration object. 40 */ 41 WASI_DECLARE_OWN(config) 42 43 /** 44 * \brief Creates a new empty configuration object. 45 * 46 * The caller is expected to deallocate the returned configuration 47 */ 48 WASI_API_EXTERN own wasi_config_t *wasi_config_new(); 49 50 /** 51 * \brief Sets the argv list for this configuration object. 52 * 53 * By default WASI programs have an empty argv list, but this can be used to 54 * explicitly specify what the argv list for the program is. 55 * 56 * The arguments are copied into the `config` object as part of this function 57 * call, so the `argv` pointer only needs to stay alive for this function call. 58 * 59 * This function returns `true` if all arguments were registered successfully, 60 * or `false` if an argument was not valid UTF-8. 61 */ 62 WASI_API_EXTERN bool wasi_config_set_argv(wasi_config_t *config, size_t argc, 63 const char *argv[]); 64 65 /** 66 * \brief Indicates that the argv list should be inherited from this process's 67 * argv list. 68 */ 69 WASI_API_EXTERN void wasi_config_inherit_argv(wasi_config_t *config); 70 71 /** 72 * \brief Sets the list of environment variables available to the WASI instance. 73 * 74 * By default WASI programs have a blank environment, but this can be used to 75 * define some environment variables for them. 76 * 77 * It is required that the `names` and `values` lists both have `envc` entries. 78 * 79 * The env vars are copied into the `config` object as part of this function 80 * call, so the `names` and `values` pointers only need to stay alive for this 81 * function call. 82 * 83 * This function returns `true` if all environment variables were successfully 84 * registered. This returns `false` if environment variables are not valid 85 * UTF-8. 86 */ 87 WASI_API_EXTERN bool wasi_config_set_env(wasi_config_t *config, size_t envc, 88 const char *names[], 89 const char *values[]); 90 91 /** 92 * \brief Indicates that the entire environment of the calling process should be 93 * inherited by this WASI configuration. 94 */ 95 WASI_API_EXTERN void wasi_config_inherit_env(wasi_config_t *config); 96 97 /** 98 * \brief Configures standard input to be taken from the specified file. 99 * 100 * By default WASI programs have no stdin, but this configures the specified 101 * file to be used as stdin for this configuration. 102 * 103 * If the stdin location does not exist or it cannot be opened for reading then 104 * `false` is returned. Otherwise `true` is returned. 105 */ 106 WASI_API_EXTERN bool wasi_config_set_stdin_file(wasi_config_t *config, 107 const char *path); 108 109 /** 110 * \brief Configures standard input to be taken from the specified 111 * #wasm_byte_vec_t. 112 * 113 * By default WASI programs have no stdin, but this configures the specified 114 * bytes to be used as stdin for this configuration. 115 * 116 * This function takes ownership of the `binary` argument. 117 */ 118 WASI_API_EXTERN void wasi_config_set_stdin_bytes(wasi_config_t *config, 119 wasm_byte_vec_t *binary); 120 121 /** 122 * \brief Configures this process's own stdin stream to be used as stdin for 123 * this WASI configuration. 124 */ 125 WASI_API_EXTERN void wasi_config_inherit_stdin(wasi_config_t *config); 126 127 /** 128 * \brief Configures standard output to be written to the specified file. 129 * 130 * By default WASI programs have no stdout, but this configures the specified 131 * file to be used as stdout. 132 * 133 * If the stdout location could not be opened for writing then `false` is 134 * returned. Otherwise `true` is returned. 135 */ 136 WASI_API_EXTERN bool wasi_config_set_stdout_file(wasi_config_t *config, 137 const char *path); 138 139 /** 140 * \brief Configures this process's own stdout stream to be used as stdout for 141 * this WASI configuration. 142 */ 143 WASI_API_EXTERN void wasi_config_inherit_stdout(wasi_config_t *config); 144 145 /** 146 * \brief Configures standard output to be written to the specified file. 147 * 148 * By default WASI programs have no stderr, but this configures the specified 149 * file to be used as stderr. 150 * 151 * If the stderr location could not be opened for writing then `false` is 152 * returned. Otherwise `true` is returned. 153 */ 154 WASI_API_EXTERN bool wasi_config_set_stderr_file(wasi_config_t *config, 155 const char *path); 156 157 /** 158 * \brief Configures this process's own stderr stream to be used as stderr for 159 * this WASI configuration. 160 */ 161 WASI_API_EXTERN void wasi_config_inherit_stderr(wasi_config_t *config); 162 163 /** 164 * \brief Configures a "preopened directory" to be available to WASI APIs. 165 * 166 * By default WASI programs do not have access to anything on the filesystem. 167 * This API can be used to grant WASI programs access to a directory on the 168 * filesystem, but only that directory (its whole contents but nothing above 169 * it). 170 * 171 * The `path` argument here is a path name on the host filesystem, and 172 * `guest_path` is the name by which it will be known in wasm. 173 */ 174 WASI_API_EXTERN bool wasi_config_preopen_dir(wasi_config_t *config, 175 const char *path, 176 const char *guest_path); 177 178 #undef own 179 180 #ifdef __cplusplus 181 } // extern "C" 182 #endif 183 184 #endif // #ifdef WASI_H 185