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 #include <wasmtime/conf.h> 13 14 #ifdef WASMTIME_FEATURE_WASI 15 16 #ifndef WASI_API_EXTERN 17 #ifdef _WIN32 18 #define WASI_API_EXTERN __declspec(dllimport) 19 #else 20 #define WASI_API_EXTERN 21 #endif 22 #endif 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 #define own 29 30 #define WASI_DECLARE_OWN(name) \ 31 typedef struct wasi_##name##_t wasi_##name##_t; \ 32 WASI_API_EXTERN void wasi_##name##_delete(own wasi_##name##_t *); 33 34 /** 35 * \typedef wasi_config_t 36 * \brief Convenience alias for #wasi_config_t 37 * 38 * \struct wasi_config_t 39 * \brief TODO 40 * 41 * \fn void wasi_config_delete(wasi_config_t *); 42 * \brief Deletes a configuration object. 43 */ 44 WASI_DECLARE_OWN(config) 45 46 /** 47 * \brief Creates a new empty configuration object. 48 * 49 * The caller is expected to deallocate the returned configuration 50 */ 51 WASI_API_EXTERN own wasi_config_t *wasi_config_new(); 52 53 /** 54 * \brief Sets the argv list for this configuration object. 55 * 56 * By default WASI programs have an empty argv list, but this can be used to 57 * explicitly specify what the argv list for the program is. 58 * 59 * The arguments are copied into the `config` object as part of this function 60 * call, so the `argv` pointer only needs to stay alive for this function call. 61 * 62 * This function returns `true` if all arguments were registered successfully, 63 * or `false` if an argument was not valid UTF-8. 64 */ 65 WASI_API_EXTERN bool wasi_config_set_argv(wasi_config_t *config, size_t argc, 66 const char *argv[]); 67 68 /** 69 * \brief Indicates that the argv list should be inherited from this process's 70 * argv list. 71 */ 72 WASI_API_EXTERN void wasi_config_inherit_argv(wasi_config_t *config); 73 74 /** 75 * \brief Sets the list of environment variables available to the WASI instance. 76 * 77 * By default WASI programs have a blank environment, but this can be used to 78 * define some environment variables for them. 79 * 80 * It is required that the `names` and `values` lists both have `envc` entries. 81 * 82 * The env vars are copied into the `config` object as part of this function 83 * call, so the `names` and `values` pointers only need to stay alive for this 84 * function call. 85 * 86 * This function returns `true` if all environment variables were successfully 87 * registered. This returns `false` if environment variables are not valid 88 * UTF-8. 89 */ 90 WASI_API_EXTERN bool wasi_config_set_env(wasi_config_t *config, size_t envc, 91 const char *names[], 92 const char *values[]); 93 94 /** 95 * \brief Indicates that the entire environment of the calling process should be 96 * inherited by this WASI configuration. 97 */ 98 WASI_API_EXTERN void wasi_config_inherit_env(wasi_config_t *config); 99 100 /** 101 * \brief Configures standard input to be taken from the specified file. 102 * 103 * By default WASI programs have no stdin, but this configures the specified 104 * file to be used as stdin for this configuration. 105 * 106 * If the stdin location does not exist or it cannot be opened for reading then 107 * `false` is returned. Otherwise `true` is returned. 108 */ 109 WASI_API_EXTERN bool wasi_config_set_stdin_file(wasi_config_t *config, 110 const char *path); 111 112 /** 113 * \brief Configures standard input to be taken from the specified 114 * #wasm_byte_vec_t. 115 * 116 * By default WASI programs have no stdin, but this configures the specified 117 * bytes to be used as stdin for this configuration. 118 * 119 * This function takes ownership of the `binary` argument. 120 */ 121 WASI_API_EXTERN void wasi_config_set_stdin_bytes(wasi_config_t *config, 122 wasm_byte_vec_t *binary); 123 124 /** 125 * \brief Configures this process's own stdin stream to be used as stdin for 126 * this WASI configuration. 127 */ 128 WASI_API_EXTERN void wasi_config_inherit_stdin(wasi_config_t *config); 129 130 /** 131 * \brief Configures standard output to be written to the specified file. 132 * 133 * By default WASI programs have no stdout, but this configures the specified 134 * file to be used as stdout. 135 * 136 * If the stdout location could not be opened for writing then `false` is 137 * returned. Otherwise `true` is returned. 138 */ 139 WASI_API_EXTERN bool wasi_config_set_stdout_file(wasi_config_t *config, 140 const char *path); 141 142 /** 143 * \brief Configures this process's own stdout stream to be used as stdout for 144 * this WASI configuration. 145 */ 146 WASI_API_EXTERN void wasi_config_inherit_stdout(wasi_config_t *config); 147 148 /** 149 * \brief Configures standard output to be directed to \p callback 150 * 151 * \param config The config to operate on 152 * \param callback A non-null callback must be provided, that will get called 153 * for each write with the buffer. A positive return value indicates the amount 154 * of bytes written. Negative return values are treated as OS error codes. 155 * \param data An optional user provided data that will be passed to \p callback 156 * \param finalizer An optional callback to be called to destroy \p data 157 */ 158 WASI_API_EXTERN void wasi_config_set_stdout_custom( 159 wasi_config_t *config, 160 ptrdiff_t (*callback)(void *, const unsigned char *, size_t), void *data, 161 void (*finalizer)(void *)); 162 163 /** 164 * \brief Configures standard output to be written to the specified file. 165 * 166 * By default WASI programs have no stderr, but this configures the specified 167 * file to be used as stderr. 168 * 169 * If the stderr location could not be opened for writing then `false` is 170 * returned. Otherwise `true` is returned. 171 */ 172 WASI_API_EXTERN bool wasi_config_set_stderr_file(wasi_config_t *config, 173 const char *path); 174 175 /** 176 * \brief Configures this process's own stderr stream to be used as stderr for 177 * this WASI configuration. 178 */ 179 WASI_API_EXTERN void wasi_config_inherit_stderr(wasi_config_t *config); 180 181 /** 182 * \brief Configures standard error output to be directed to \p callback 183 * 184 * \param config The config to operate on 185 * \param callback A non-null callback must be provided, that will get called 186 * for each write with the buffer. A positive return value indicates the amount 187 * of bytes written. Negative return values are treated as OS error codes. 188 * \param data An optional user provided data that will be passed to \p callback 189 * \param finalizer An optional callback to be called to destroy \p data 190 */ 191 WASI_API_EXTERN void wasi_config_set_stderr_custom( 192 wasi_config_t *config, 193 ptrdiff_t (*callback)(void *, const unsigned char *, size_t), void *data, 194 void (*finalizer)(void *)); 195 196 /** 197 * \brief The permissions granted for a directory when preopening it. 198 */ 199 enum wasi_dir_perms_flags { 200 /** 201 * \brief This directory can be read, for example its entries can be iterated 202 */ 203 WASMTIME_WASI_DIR_PERMS_READ = 1, 204 205 /** 206 * \brief This directory can be written to, for example new files can be 207 * created within it. 208 */ 209 WASMTIME_WASI_DIR_PERMS_WRITE = 2, 210 }; 211 212 /** 213 * \brief The permissions granted for directories when preopening them, 214 * which is a bitmask with flag values from wasi_dir_perms_flags. 215 */ 216 typedef size_t wasi_dir_perms; 217 218 /** 219 * \brief The permissions granted for files when preopening a directory. 220 */ 221 enum wasi_file_perms_flags { 222 /** 223 * \brief Files can be read. 224 */ 225 WASMTIME_WASI_FILE_PERMS_READ = 1, 226 227 /** 228 * \brief Files can be written to. 229 */ 230 WASMTIME_WASI_FILE_PERMS_WRITE = 2, 231 }; 232 233 /** 234 * \brief The max permissions granted a file within a preopened directory, 235 * which is a bitmask with flag values from wasi_file_perms_flags. 236 */ 237 typedef size_t wasi_file_perms; 238 239 /** 240 * \brief Configures a "preopened directory" to be available to WASI APIs. 241 * 242 * By default WASI programs do not have access to anything on the filesystem. 243 * This API can be used to grant WASI programs access to a directory on the 244 * filesystem, but only that directory (its whole contents but nothing above 245 * it). 246 * 247 * The `host_path` argument here is a path name on the host filesystem, and 248 * `guest_path` is the name by which it will be known in wasm. 249 * 250 * The `dir_perms` argument is the permissions that wasm will have to operate on 251 * `guest_path`. This can be used, for example, to provide readonly access to a 252 * directory. This argument is a bitmask with the following flag values: 253 * - WASMTIME_WASI_DIR_PERMS_READ 254 * - WASMTIME_WASI_DIR_PERMS_WRITE 255 * 256 * The `file_perms` argument is similar to `dir_perms` but corresponds to the 257 * maximum set of permissions that can be used for any file in this directory. 258 * This argument is a bitmask with the following flag values: 259 * - WASMTIME_WASI_FILE_PERMS_READ 260 * - WASMTIME_WASI_FILE_PERMS_WRITE 261 */ 262 WASI_API_EXTERN bool wasi_config_preopen_dir(wasi_config_t *config, 263 const char *host_path, 264 const char *guest_path, 265 wasi_dir_perms dir_perms, 266 wasi_file_perms file_perms); 267 268 #undef own 269 270 #ifdef __cplusplus 271 } // extern "C" 272 #endif 273 274 #endif // WASMTIME_FEATURE_WASI 275 276 #endif // #ifdef WASI_H 277