1 // Copyright 2016 The Fuchsia Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #pragma once 6 7 #include <zircon/types.h> 8 #include <zircon/compiler.h> 9 #include <stdint.h> 10 #include <unistd.h> 11 12 __BEGIN_CDECLS 13 14 // These routines are "internal" to fdio but used by some companion 15 // code like userboot and devmgr 16 17 typedef struct fdio fdio_t; 18 19 // Utilities to help assemble handles for a new process 20 // may return up to FDIO_MAX_HANDLES 21 zx_status_t fdio_clone_cwd(zx_handle_t* handles, uint32_t* types); 22 zx_status_t fdio_clone_fd(int fd, int newfd, zx_handle_t* handles, uint32_t* types); 23 zx_status_t fdio_transfer_fd(int fd, int newfd, zx_handle_t* handles, uint32_t* types); 24 25 // Attempt to create an fdio fd from some handles and their associated types, 26 // as returned from fdio_transfer_fd. 27 // 28 // Can only create fds around: 29 // - Remote IO objects 30 // - Pipes 31 // - Connected sockets 32 // 33 // This function transfers ownership of handles to the fd on success, and 34 // closes them on failure. 35 zx_status_t fdio_create_fd(zx_handle_t* handles, uint32_t* types, size_t hcount, int* fd_out); 36 37 // attempt to install a fdio in the unistd fd table 38 // if fd >= 0, request a specific fd, and starting_fd is ignored 39 // if fd < 0, request the first available fd >= starting_fd 40 // returns fd on success 41 // the fdio must have been upref'd on behalf of the fdtab first 42 int fdio_bind_to_fd(fdio_t* io, int fd, int starting_fd); 43 44 // attempt to detach an fdio_t from the fd table 45 // returns ZX_ERR_INVALID_ARGS if fd is out of range or doesn't exist 46 // returns ZX_ERR_UNAVAILABLE if the fd is busy or has been dup'd 47 // returns fdio_t via io_out with refcount 1 on success 48 zx_status_t fdio_unbind_from_fd(int fd, fdio_t** io_out); 49 50 // If this fd represents a "service" (an rpc channel speaking 51 // an unknown fidl protocol or a fuchsia.io.* protocol), 52 // this call will return ZX_OK and return the underlying handle. 53 // On both success and failure, the fd is effectively closed. 54 // 55 // ZX_ERR_NOT_SUPPORTED is returned if this fd does not represent 56 // a FIDL transport 57 // 58 // ZX_ERR_UNAVAILABLE is returned if this fd has been dup()'d and 59 // duplicates are sharing the FIDL transport 60 zx_status_t fdio_get_service_handle(int fd, zx_handle_t* out); 61 62 // creates a do-nothing fdio_t 63 fdio_t* fdio_null_create(void); 64 65 // Wraps a channel with an fdio_t using remote io. 66 // Takes ownership of h and e. 67 fdio_t* fdio_remote_create(zx_handle_t h, zx_handle_t event); 68 69 // creates a fdio that wraps a log object 70 // this will allocate a per-thread buffer (on demand) to assemble 71 // entire log-lines and flush them on newline or buffer full. 72 fdio_t* fdio_logger_create(zx_handle_t); 73 74 typedef struct zxio_storage zxio_storage_t; 75 76 // Creates an |fdio_t| that is backed by a |zxio_t|. 77 // 78 // The |zxio_t| is initialized with a null ops table. The |zxio_storage_t| for 79 // the |zxio_t| is returned via |out_storage|. The client can re-initialize the 80 // |zxio_storage_t| to customize the behavior of the |zxio_t|. 81 // 82 // To bind the |fdio_t| to a file descriptor, use |fdio_bind_to_fd|. 83 // 84 // Upon failure, returns NULL. 85 fdio_t* fdio_zxio_create(zxio_storage_t** out_storage); 86 87 // Attempt to connect a channel to a named service. 88 // On success the channel is connected. On failure 89 // an error is returned and the handle is closed. 90 zx_status_t fdio_service_connect(const char* svcpath, zx_handle_t h); 91 92 // Attempt to connect a channel to a named service relative to dir. 93 // On success the channel is connected. On failure 94 // an error is returned and the handle is closed. 95 zx_status_t fdio_service_connect_at(zx_handle_t dir, const char* path, zx_handle_t h); 96 97 // Same as |fdio_service_connect|, but allows the passing of flags. 98 zx_status_t fdio_open(const char* path, uint32_t zxflags, zx_handle_t h); 99 100 // Same as |fdio_service_connect_at, but allows the passing of flags. 101 zx_status_t fdio_open_at(zx_handle_t dir, const char* path, uint32_t zxflags, zx_handle_t h); 102 103 // Attempt to clone a service handle by doing a pipelined 104 // CLONE operation, returning the new channel endpoint, 105 // or ZX_HANDLE_INVALID. 106 zx_handle_t fdio_service_clone(zx_handle_t h); 107 108 // Attempt to clone a service handle by doing a pipelined 109 // CLONE operation, using the provided serving channel. 110 // On success srv is bound to a clone of h. On failure 111 // an error is returned and srv is closed. 112 // Takes ownership of srv. 113 zx_status_t fdio_service_clone_to(zx_handle_t h, zx_handle_t srv); 114 115 __END_CDECLS 116