3 * Copyright (C) Volker Lendecke 2012
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.
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.
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/>.
22 #include <sys/types.h>
28 * @defgroup asys The async syscall library
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
35 * The basic flow of operations is:
37 * The application creates a asys_context structure using
38 * asys_context_create()
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.
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.
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
66 struct asys_creds_context
;
75 #ifndef PRINTF_ATTRIBUTE
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
81 #define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
83 #define PRINTF_ATTRIBUTE(a1, a2)
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);
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
,
97 * @brief Get the the signal fd
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.
103 * @param[in] ctx The asys context
104 * @return A file descriptor indicating a finished operation
107 int asys_signalfd(struct asys_context
*ctx
);
110 * @brief Pull the result from an async operation
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().
116 * @param[in] ctx The asys context
117 * @return success: 0, failure: errno
119 int asys_result(struct asys_context
*ctx
, ssize_t
*pret
, int *perrno
,
121 void asys_cancel(struct asys_context
*ctx
, void *private_data
);
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
,
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
);
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
);
136 int asys_creds_context_delete(struct asys_creds_context
*ctx
);
138 int asys_open(struct asys_context
*ctx
, struct asys_creds_context
*cctx
,
139 const char *pathname
, int flags
, mode_t mode
,
141 int asys_unlink(struct asys_context
*ctx
, struct asys_creds_context
*cctx
,
142 const char *pathname
, void *private_data
);
146 #endif /* __ASYS_H__ */