source3/lib/asys/asys.h

   1 /*
   2  * Async syscalls
   3  * Copyright (C) Volker Lendecke 2012
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 3 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef __ASYS_H__
  20 #define __ASYS_H__
  21
  22 #include <sys/types.h>
  23 #include <sys/stat.h>
  24 #include <fcntl.h>
  25 #include <unistd.h>
  26
  27 /**
  28  * @defgroup asys The async syscall library
  29  *
  30  * This module contains a set of asynchronous functions that directly
  31  * wrap normally synchronous posix system calls. The reason for this
  32  * module's existence is the limited set of operations the posix async
  33  * I/O API provides.
  34  *
  35  * The basic flow of operations is:
  36  *
  37  * The application creates a asys_context structure using
  38  * asys_context_create()
  39  *
  40  * The application triggers a call to the library by calling for
  41  * example asys_ftruncate(). asys_ftruncate() takes a private_data
  42  * argument that will be returned later by asys_result. The calling
  43  * application should hand a pointer representing the async operation
  44  * to the private_data argument.
  45  *
  46  * The application puts the fd returned by asys_signalfd() into its
  47  * event loop. When the signal fd becomes readable, the application
  48  * calls asys_result() to grab the final result of one of the system
  49  * calls that were issued in the meantime.
  50  *
  51  * For multi-user applications it is necessary to create different
  52  * credential contexts, as it is not clear when exactly the real
  53  * system call will be issued. The application might have called
  54  * seteuid(2) or something equivalent in the meantime. Thus, all
  55  * system calls doing access checks, in particular all calls doing
  56  * path-based operations, require a struct auth_creds_context
  57  * parameter. asys_creds_context_create() creates such a context. All
  58  * credential-checking operations take a struct asys_creds_context as
  59  * an argument. It can be NULL if the application never changes
  60  * credentials.
  61  *
  62  * @{
  63  */
  64
  65 struct asys_context;
  66 struct asys_creds_context;
  67
  68 enum asys_log_level {
  69         ASYS_LOG_FATAL = 0,
  70         ASYS_DEBUG_ERROR,
  71         ASYS_DEBUG_WARNING,
  72         ASYS_DEBUG_TRACE
  73 };
  74
  75 #ifndef PRINTF_ATTRIBUTE
  76 #if (__GNUC__ >= 3)
  77 /** Use gcc attribute to check printf fns.  a1 is the 1-based index of
  78  * the parameter containing the format, and a2 the index of the first
  79  * argument. Note that some gcc 2.x versions don't handle this
  80  * properly **/
  81 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
  82 #else
  83 #define PRINTF_ATTRIBUTE(a1, a2)
  84 #endif
  85 #endif
  86
  87 typedef void (*asys_log_fn)(struct asys_context *ctx, void *private_data,
  88                             enum asys_log_level level,
  89                             const char *fmt, ...) PRINTF_ATTRIBUTE(4, 5);
  90
  91 int asys_context_init(struct asys_context **ctx, unsigned max_parallel);
  92 int asys_context_destroy(struct asys_context *ctx);
  93 void asys_set_log_fn(struct asys_context *ctx, asys_log_fn fn,
  94                      void *private_data);
  95
  96 /**
  97  * @brief Get the the signal fd
  98  *
  99  * asys_signalfd() returns a file descriptor that will become readable
 100  * whenever an asynchronous request has finished. When the signalfd is
 101  * readable, calling asys_result() will not block.
 102  *
 103  * @param[in]   ctx     The asys context
 104  * @return              A file descriptor indicating a finished operation
 105  */
 106
 107 int asys_signalfd(struct asys_context *ctx);
 108
 109 /**
 110  * @brief Pull the result from an async operation
 111  *
 112  * Whe the fd returned from asys_signalfd() is readable, an async
 113  * operation has finished. The result from the async operation can be
 114  * pulled with asys_result().
 115  *
 116  * @param[in]   ctx     The asys context
 117  * @return              success: 0, failure: errno
 118  */
 119 int asys_result(struct asys_context *ctx, ssize_t *pret, int *perrno,
 120                 void *pdata);
 121 void asys_cancel(struct asys_context *ctx, void *private_data);
 122
 123 int asys_pread(struct asys_context *ctx, int fildes, void *buf, size_t nbyte,
 124                off_t offset, void *private_data);
 125 int asys_pwrite(struct asys_context *ctx, int fildes, const void *buf,
 126                 size_t nbyte, off_t offset, void *private_data);
 127 int asys_ftruncate(struct asys_context *ctx, int filedes, off_t length,
 128                    void *private_data);
 129 int asys_fsync(struct asys_context *ctx, int fd, void *private_data);
 130 int asys_close(struct asys_context *ctx, int fd, void *private_data);
 131
 132 struct asys_creds_context *asys_creds_context_create(
 133         struct asys_context *ctx,
 134         uid_t uid, gid_t gid, unsigned num_gids, gid_t *gids);
 135
 136 int asys_creds_context_delete(struct asys_creds_context *ctx);
 137
 138 int asys_open(struct asys_context *ctx, struct asys_creds_context *cctx,
 139               const char *pathname, int flags, mode_t mode,
 140               void *private_data);
 141 int asys_unlink(struct asys_context *ctx, struct asys_creds_context *cctx,
 142                 const char *pathname, void *private_data);
 143
 144 /* @} */
 145
 146 #endif /* __ASYS_H__ */