zircon/system/ulib/fdio/include/lib/fdio/namespace.h

// Copyright 2017 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.

#ifndef LIB_FDIO_NAMESPACE_H_
#define LIB_FDIO_NAMESPACE_H_

#include <stdint.h>

#include <zircon/compiler.h>
#include <zircon/types.h>

__BEGIN_CDECLS

typedef struct fdio_namespace fdio_ns_t;

// Create a new, empty namespace
zx_status_t fdio_ns_create(fdio_ns_t** out);

// Destroy and deallocate a namespace.
//
// If the namespace is in-use, it will be destroyed once it is
// no longer referenced.
//
// This function always returns |ZX_OK|.
zx_status_t fdio_ns_destroy(fdio_ns_t* ns);

// Create a new directory within a namespace, bound to the
// directory-protocol-compatible handle h
// The path must be an absolute path, like "/x/y/z", containing
// no "." nor ".." entries.  It is relative to the root of the
// namespace.
//
// Ownership of |h| is transferred to |ns|: it is closed on error.
zx_status_t fdio_ns_bind(fdio_ns_t* ns, const char* path, zx_handle_t h);

// Unbinds |path| from a namespace, closing the handle within |ns| that
// corresponds to that path when all references to the node go out of scope.
//
// Returns ZX_ERR_NOT_FOUND if |path| is not a remote.
// Returns ZX_ERR_NOT_SUPPORTED if |path| is the root of the namespace.
// Returns ZX_ERR_INVALID_ARGS if |path| is otherwise invalid.
zx_status_t fdio_ns_unbind(fdio_ns_t* ns, const char* path);

// Create a new directory within a namespace, bound to the
// directory referenced by the file descriptor fd.
// The path must be an absolute path, like "/x/y/z", containing
// no "." nor ".." entries.  It is relative to the root of the
// namespace.
//
// |fd| is borrowed by this function, but is not closed on success or error.
// Closing the fd after success does not affect namespace.
//
// Failures:
// ZX_ERR_BAD_STATE: Namespace is already in use and immutable.
// ZX_ERR_ALREADY_EXISTS: There is already a mounted directory there.
// ZX_ERR_NOT_SUPPORTED: This path would shadow a mounted directory.
zx_status_t fdio_ns_bind_fd(fdio_ns_t* ns, const char* path, int fd);

// Open the root directory of the namespace as a file descriptor
int fdio_ns_opendir(fdio_ns_t* ns);

// chdir to / in the provided namespace
zx_status_t fdio_ns_chdir(fdio_ns_t* ns);

// Retrieve the fdio "global" namespace (if any).
zx_status_t fdio_ns_get_installed(fdio_ns_t** ns);

typedef struct fdio_flat_namespace {
    size_t count;
    zx_handle_t* handle;
    uint32_t* type;
    const char* const* path;
} fdio_flat_namespace_t;

// On success the caller takes ownership of a fdio_flat_namespace_t
// containing a flat representation of the exported namespace (the
// one provided in 'ns' or the active root namespace, respectively.)
// The handles are CLONEs of the handles in the namespace and also
// belong to the caller.
// The whole data structure can be released with fdio_ns_free_flat_ns().
zx_status_t fdio_ns_export(fdio_ns_t* ns, fdio_flat_namespace_t** out);
zx_status_t fdio_ns_export_root(fdio_flat_namespace_t** out);

// Attempt to connect to a service through the namespace.
// The handle is always consumed.  It will be closed on error
// or passed to the remote service on success.
// The path must be an absolute path starting with / and containing
// no ".." or "." or empty segments.
zx_status_t fdio_ns_connect(fdio_ns_t* ns, const char* path,
                            uint32_t zxflags, zx_handle_t h);

// Attempt a pipelined open through a namespace.
// Success only indicates that the open was sent.
// If the remote fails, the returned handle's peer will be closed.
// The path must be an absolute path starting with / and containing
// no ".." or "." or empty segments.
zx_status_t fdio_ns_open(fdio_ns_t* ns, const char* path,
                         uint32_t zxflags, zx_handle_t* out);

// Frees a flat namespace.
// Closes all handles contained within |ns|.
void fdio_ns_free_flat_ns(fdio_flat_namespace_t* ns);

__END_CDECLS

#endif  // LIB_FDIO_NAMESPACE_H_