zircon/system/ulib/test-utils/include/test-utils/test-utils.h

// Copyright 2016 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#pragma once

// This file is a collection of utilities for writing tests.
// Typically they are wrappers on system calls and other routines
// and save the caller from having to test the return code (for cases
// where there's no point in continuing with the test if the call fails).
// Note that if these calls fail they cause the process to exit, and
// are not intended to be used for tests that have multiple "subtests"
// and it's reasonable to continue with the other subtests if a syscall
// in one fails.

#include <stddef.h>
#include <threads.h>
#include <zircon/types.h>
#include <zircon/compiler.h>
#include <zircon/syscalls/object.h>
#include <launchpad/launchpad.h>

__BEGIN_CDECLS

// These malloc-using calls will terminate the process on ENOMEM.
void* tu_malloc(size_t size);
void* tu_calloc(size_t nmemb, size_t size);
char* tu_strdup(const char* s);
char* tu_asprintf(const char* fmt, ...);

// Print a message saying a syscall (or similar) function failed,
// and terminate the process.
// |what| is typically the name of the function that had the syscall failure,
// but it can include more descriptive text as desired.

void tu_fatal(const char *what, zx_status_t status) __NO_RETURN;

// A wrapper on zx_handle_close.

void tu_handle_close(zx_handle_t handle);

// A wrapper on zx_handle_duplicate.

zx_handle_t tu_handle_duplicate(zx_handle_t handle);

// A wrapper on launchpad_launch.

zx_handle_t tu_launch(zx_handle_t job, const char* name,
                      int argc, const char* const* argv,
                      const char* const* envp,
                      size_t num_handles, zx_handle_t* handles,
                      uint32_t* handle_ids);

// The first part of launchpad_launch_fdio_etc that creates the
// launchpad and initializes the process.

launchpad_t* tu_launch_fdio_init(zx_handle_t job, const char* name,
                                 int argc, const char* const* argv,
                                 const char* const* envp,
                                 size_t num_handles, zx_handle_t* handles,
                                 uint32_t* handle_ids);

// The second part of launchpad_launch_fdio_etc that starts the process.
// Returns a handle of the started process.

zx_handle_t tu_launch_fdio_fini(launchpad_t* lp);

// A wrapper on C11 thrd_create.

void tu_thread_create_c11(thrd_t* thread, thrd_start_t entry, void* arg,
                          const char* name);

// A wrapper on zx_object_wait_many that can be easier to call.
// |num_objects| is the number of elements in |handles,signals,pending|.

zx_status_t tu_wait(uint32_t num_objects,
                    const zx_handle_t* handles,
                    const zx_signals_t* signals,
                    zx_signals_t* pending);

// A wrapper on zx_channel_create.

void tu_channel_create(zx_handle_t* handle0, zx_handle_t* handle1);


// A wrapper on zx_channel_write.

void tu_channel_write(zx_handle_t handle, uint32_t flags, const void* bytes, uint32_t num_bytes,
                      const zx_handle_t* handles, uint32_t num_handles);

// A wrapper on zx_channel_read.

void tu_channel_read(zx_handle_t handle, uint32_t flags, void* bytes, uint32_t* num_bytes,
                     zx_handle_t* handles, uint32_t* num_handles);

// Wait for |channel| to be readable.
// Returns true if the channel is readable, and false if the peer has closed its end.
// Note: This waits "forever", and relies on the watchdog to catch hung tests.
bool tu_channel_wait_readable(zx_handle_t channel);

// Wait for |process| to be signaled (ZX_PROCESS_TERMINATED).
// Note: This waits "forever", and relies on the watchdog to catch hung tests.

void tu_process_wait_signaled(zx_handle_t process);

// Return true if |process| has exited.

bool tu_process_has_exited(zx_handle_t process);

// Fetch the return code of |process|.

int tu_process_get_return_code(zx_handle_t process);

// Wait for |process| to exit and then fetch its return code.

int tu_process_wait_exit(zx_handle_t process);

// Return the handle of thread |tid| in |process|.
// Returns ZX_HANDLE_INVALID if the thread is not found (could have died).

zx_handle_t tu_process_get_thread(zx_handle_t process, zx_koid_t tid);

// Fetch the current threads of |process|.
// |max_threads| is the size of the |threads| buffer.
// Returns the actual number of threads at the point in time when the list
// of threads is obtained. It could be larger than |max_threads|.
// See discussion of ZX_INFO_PROCESS_THREADS in object_get_info.md.

size_t tu_process_get_threads(zx_handle_t process, zx_koid_t* threads, size_t max_threads);

// Create a child job of |job|.

zx_handle_t tu_job_create(zx_handle_t job);

// Create an io port.

zx_handle_t tu_io_port_create(void);

// Set the exception port for |handle| which is a process or thread.

void tu_set_exception_port(zx_handle_t handle, zx_handle_t eport, uint64_t key, uint32_t options);

// Add |handle| to the list of things |port| watches.
// When |handle| is signaled with a signal in |signals| a zx_packet_signal_t
// packet is sent to |port| with the key being the koid of |handle|.
void tu_object_wait_async(zx_handle_t handle, zx_handle_t port, zx_signals_t signals);

// Get basic handle info for |handle|.

void tu_handle_get_basic_info(zx_handle_t handle, zx_info_handle_basic_t* info);

// Return the koid of the object of |handle|.

zx_koid_t tu_get_koid(zx_handle_t handle);

// Return the "related" koid of the object of |handle|.

zx_koid_t tu_get_related_koid(zx_handle_t handle);

// Return a handle of thread |tid|.

zx_handle_t tu_get_thread(zx_handle_t proc, zx_koid_t tid);

// Return zx_info_thread_t of |thread|.

zx_info_thread_t tu_thread_get_info(zx_handle_t thread);

// Return the state of |thread|, one of ZX_THREAD_STATE_*.

uint32_t tu_thread_get_state(zx_handle_t thread);

// Return true if |thread| is dying or dead.

bool tu_thread_is_dying_or_dead(zx_handle_t thread);

// Kill |task|.

void tu_task_kill(zx_handle_t task);

// Run a program and wait for it to exit.
// Any error in trying to run the program is fatal.
// The result is the return code of the child process.

int tu_run_program(const char *progname, int argc, const char** argv);

// A wrapper for /bin/sh -c <command>.

int tu_run_command(const char* progname, const char* cmd);

// Set the scaling factor for timeouts.
// The default is 1. A value of 2 waits twice as long, and so on.
// This is useful when running tests under a debugger or with a
// massive amount of tracing turned on.
// If 0 is passed no change is made.
// Returns the previous value.

int tu_set_timeout_scale(int scale);

__END_CDECLS