source: trunk/libs/stdio.h @ 420

Last change on this file since 420 was 412, checked in by alain, 7 years ago

Introduce user libraries
File size: 19.3 KB
Line 
1/*
2 * stdio.h - User side syscalls definition.
3 *
4 * Author     Alain Greiner (2016,2017)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH.
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _STDIO_H_
25#define _STDIO_H_
26
27#include <shared_syscalls.h>
28
29#define  NULL  (void *)0
30
31/*****************************************************************************************
32 * This function terminates a process.
33 *****************************************************************************************
34 * @ status   : terminaison status : 0 / EXIT_SUCCESS / EXIT_FAILURE.
35 ****************************************************************************************/
36void exit( int status );
37
38/*****************************************************************************************
39 * This function open or create an open file descriptor.
40 *****************************************************************************************
41 * @ pathname   : pathname (can be relative or absolute).
42 * @ flags      : bit vector attributes (see syscalls).
43 * @ mode       : access rights (if O_CREAT is set).
44 * @ return file descriptor index in fd_array if success / return -1 if failure.
45 ****************************************************************************************/
46int open( const char * pathname,
47          int          flags,
48          int          mode );
49
50/*****************************************************************************************
51 * This function map physical memory (or a file) in the calling thread virtual space.
52 *****************************************************************************************
53 * @ addr       : unused and unsupported : must be NULL.
54 * @ length     : requested number of bytes.
55 * @ prot       : RWX access modes.
56 * @ flags      : MAP_FILE / MAP_ANON / MAP_PRIVATE / MAP_SHARED (defined in syscalls.h) 
57 * @ fdid       : file descriptor index (if MAP_FILE).                     
58 * @ offset         : offset in file (if MAP_FILE)
59 * @ return 0 if success / return -1 if failure.
60 ****************************************************************************************/
61void * mmap( void         * addr,
62             unsigned int   length,
63             int            prot,
64             int            flags,
65             int            fd,
66             unsigned int   offset );
67
68/*****************************************************************************************
69 * This function read bytes from an open file identified by its file descriptor.
70 * This file can be a regular file or a character oriented device.
71 *****************************************************************************************
72 * @ file_id  : open file index in fd_array.
73 * @ buf      : buffer virtual address in user space.
74 * @ count    : number of bytes.
75 * @ return number of bytes actually read if success / returns -1 if failure.
76 ****************************************************************************************/
77int read( int            fd,
78          void         * buf,
79          unsigned int   count );
80
81/*****************************************************************************************
82 * This function writes bytes to an open file identified by its file descriptor.
83 * This file can be a regular file or character oriented device.
84 *****************************************************************************************
85 * @ file_id  : open file index in fd_array.
86 * @ buf      : buffer virtual address in user space.
87 * @ count    : number of bytes.
88 * @ return number of bytes actually written if success / returns -1 if failure.
89 ****************************************************************************************/
90int write( int            fd,
91           const void   * buf,
92           unsigned int   count );
93
94/*****************************************************************************************
95 * This function repositions the offset of the file descriptor identified by <file_id>,
96 * according to the operation type defined by the <whence> argument.
97 *****************************************************************************************
98 * @ fd       : open file index in fd_array.
99 * @ offset   : used to compute new offset value.
100 * @ whence   : operation type (SEEK_SET / SEEK_CUR / SEEK_END defined in syscalls.h)
101 * @ return 0 if success / returns -1 if failure.
102 ****************************************************************************************/
103int lseek( int           fd,
104           unsigned int  offset,
105           int           whence );
106
107/*****************************************************************************************
108 * This function release the memory allocated for the file descriptor identified by
109 * the <file_id> argument, and remove the fd array_entry in all copies of the process
110 * descriptor.
111 *****************************************************************************************
112 * fd   : file descriptor index in fd_array.
113 * @ return 0 if success / returns -1 if failure.
114 ****************************************************************************************/
115int close( int fd );
116
117/*****************************************************************************************
118 * This function removes a directory entry identified by the <pathname> from the
119 * directory, and decrement the link count of the file referenced by the link.
120 * If the link count reduces to zero, and no process has the file open, then all resources
121 * associated with the file are released.  If one or more process have the file open when
122 * the last link is removed, the link is removed, but the removal of the file is delayed
123 * until all references to it have been closed.
124 *****************************************************************************************
125 * @ pathname   : pathname (can be relative or absolute).
126 * @ return 0 if success / returns -1 if failure.
127 ****************************************************************************************/
128int unlink( const char * pathname );
129
130/*****************************************************************************************
131 * This function creates in the calling thread cluster an unnamed pipe, and two
132 * (read and write) file descriptors to access this pipe. The calling function must pass
133 * the pointer on the fd[] array.
134 * TODO not implemented yet...
135 *****************************************************************************************
136 * @ file_id[0] : [out] read only file descriptor index.
137 * @ file_id[1] : [out] write only file descriptor index.
138 * @ return 0 if success / return -1 if failure.
139 ****************************************************************************************/
140int pipe( int fd[2] );
141
142/*****************************************************************************************
143 * This function change the current working directory in reference process descriptor.
144 *****************************************************************************************
145 * @ pathname   : pathname (can be relative or absolute).
146 * @ return 0 if success / returns -1 if failure.
147 ****************************************************************************************/
148int chdir( const char * pathname );
149
150/*****************************************************************************************
151 * This function creates a new directory in file system.
152 *****************************************************************************************
153 * @ pathname   : pathname (can be relative or absolute).
154 * @ mode       : access rights (as defined in chmod).
155 * @ return 0 if success / returns -1 if failure.
156 ****************************************************************************************/
157int mkdir( const char * pathname,
158           int          mode );
159
160/*****************************************************************************************
161 * This function creates a named FIFO file in the calling thread cluster.
162 * The associated read and write file descriptors mut be be  explicitely created
163 * using the open() system call.
164 *****************************************************************************************
165 * @ pathname   : pathname (can be relative or absolute).
166 * @ mode       : access rights (as defined in chmod).
167 * @ return 0 if success / returns -1 if failure.
168 ****************************************************************************************/
169int mkfifo( const char * pathname,
170            int          mode );
171
172/*****************************************************************************************
173 * This function opens the directory identified by the <pathname> argument,
174 * associates a directory stream with it and returns an user space pointer to identify
175 * this directory stream in subsequent operations. 
176 *****************************************************************************************
177 * @ pathname   : pathname (can be relative or absolute).
178 * @ returns DIR* pointer if success / returns NULL if pathname cannot be accessed.
179 ****************************************************************************************/
180DIR * opendir( const char * pathname );
181
182/*****************************************************************************************
183 * This function returns a pointer to the next directory entry.
184 *****************************************************************************************
185 * @ dirp     : DIR pointer identifying the directory.
186 * @ returns dirent* pointer / returns NULL upon reaching end of directory or on error.
187 ****************************************************************************************/
188struct dirent * readdir( DIR * dirp );
189
190/*****************************************************************************************
191 * This function closes the directory identified by the <dirp> argument, and releases
192 * all structures associated with the <dirp> pointer.
193 *****************************************************************************************
194 * @ dirp     : DIR pointer identifying the directory.
195 * @ returns 0 if success / returns -1 if failure.
196 ****************************************************************************************/
197int closedir( DIR * dirp );
198
199/*****************************************************************************************
200 * This function returns the pathname of the current working directory.
201 *****************************************************************************************
202 * buf     : buffer addres in user space.
203 * nbytes  : user buffer size in bytes.
204 * @ return 0 if success / returns -1 if failure.
205 ****************************************************************************************/
206int getcwd( char       * buf,
207            unsigned int nbytes );
208
209/*****************************************************************************************
210 * This function removes a directory file whose name is given by <pathname>.
211 * The directory must not have any entries other than `.' and `..'.
212 *****************************************************************************************
213 * @ pathname   : pathname (can be relative or absolute).
214 * @ return 0 if success / returns -1 if failure.
215 ****************************************************************************************/
216int rmdir( char * pathname ); 
217
218/*****************************************************************************************
219 * This function implement the operations related to User Thread Local Storage.
220 *****************************************************************************************
221 * @ operation  : UTLS operation type as defined in "shared_sycalls.h" file.
222 * @ value      : argument value for the UTLS_SET operation.
223 * @ return value for the UTLS_GET and UTLS_GET_ERRNO / return -1 if failure.
224 ****************************************************************************************/
225int utls( unsigned int operation,
226          unsigned int value );
227
228/*****************************************************************************************
229 * This function change the acces rights for the file/dir identified by the
230 * pathname argument.
231 *****************************************************************************************
232 * @ pathname   : pathname (can be relative or absolute).
233 * @ rights     : acces rights.
234 * @ return 0 if success / returns -1 if failure.
235 ****************************************************************************************/
236int chmod( char     * pathname,
237           unsigned int   rights );
238
239/*****************************************************************************************
240 * This function associate a specific signal handler to a given signal type.
241 * The handlers for the SIGKILL and SIGSTOP signals cannot be redefined.
242 *****************************************************************************************
243 * @ sig_id    : index defining signal type (from 1 to 31).
244 * @ handler   : pointer on fonction implementing the specific handler.
245 * @ return 0 if success / returns -1 if failure.
246 ****************************************************************************************/
247int signal( unsigned int   sig_id,
248            void         * handler );
249
250/*****************************************************************************************
251 * This function returns in the structure <tv>, defined in the time.h file,
252 * the current time (in seconds & micro-seconds).
253 * It is computed from the calling core descriptor.
254 * The timezone is not supported.
255 *****************************************************************************************
256 * @ tv      : pointer on the timeval structure.
257 * @ tz      : pointer on the timezone structure : must be NULL.       
258 * @ return 0 if success / returns -1 if failure.
259 ****************************************************************************************/
260int gettimeofday( struct timeval  * tv,
261                  struct timezone * tz );
262
263/*****************************************************************************************
264 * This function implements the POSIX "kill" system call.
265 * It register the signal defined by the <sig_id> argument in all thread descriptors
266 * of a target process identified by the <pid> argument. This is done in all clusters
267 * containing threads for the target process.
268 *****************************************************************************************
269 * @ pid      : target process identifier.
270 * @ sig_id   : index defining the signal type (from 1 to 31).
271 * @ return 0 if success / returns -1 if failure.
272 ****************************************************************************************/
273int kill( unsigned int  pid,
274          unsigned int  sig_id );
275
276/*****************************************************************************************
277 * This function implements the POSIX "getpid" system call.
278 *****************************************************************************************
279 * @ returns the process PID for the calling thread.
280 ****************************************************************************************/
281int getpid();
282
283/*****************************************************************************************
284 * This function implement the POSIX "fork" system call.
285 * The calling process descriptor (parent process), and the associated thread descriptor
286 * are replicated in the same cluster as the calling thread, but the new process (child
287 * process) is registered in another target cluster, that is the new process owner.
288 * The child process and the associated main thread will be migrated to the target cluster
289 * later, when the child process makes an "exec" or any other system call.
290 * The target cluster depends on the "fork_user" flag and "fork_cxy" variable that can be
291 * stored in the calling thread descriptor by the specific fork_place() system call.
292 * If not, the kernel function makes a query to the DQDT to select the target cluster.
293 *****************************************************************************************
294 * @ returns child process PID if success / returns -1 if failure
295 ****************************************************************************************/
296int fork();
297
298/*****************************************************************************************
299 * This function implement the "exec" system call.
300 * It is executed in the client cluster, but the new process descriptor and main thread
301 * must be created in a server cluster, that is generally another cluster.
302 * - if the server_cluster is the client cluster, call directly the process_make_exec()
303 *   function to create a new process, and launch a new thread in local cluster.
304 * - if the target_cluster is remote, call rpc_process_exec_client() to execute the
305 *   process_make_exec() on the remote cluster.
306 * In both case this function build an exec_info_t structure containing all informations
307 * required to build the new process descriptor and the associated thread.
308 * Finally, the calling process and thread are deleted.
309 *****************************************************************************************
310 * @ filename : string pointer on .elf filename (virtual pointer in user space)
311 * @ argv     : array of strings on process arguments (virtual pointers in user space)
312 * @ envp     : array of strings on environment variables (virtual pointers in user space)
313 * @ returns O if success / returns -1 if failure.
314 ****************************************************************************************/
315int exec( char  * filename,
316          char ** argv,
317          char ** envp );
318
319/*****************************************************************************************
320 * This function  returns in the <stat> structure, defined in the "shared_syscalls.h"
321 * file, various informations on the file/directory identified by the <pathname> argument.
322 *****************************************************************************************
323 * @ pathname  : user pointer on file pathname.
324 * @ stat      : user pointer on the stat structure.
325 * @ returns O if success / returns -1 if failure.
326 ****************************************************************************************/
327int stat( const char  * pathname,
328          struct stat * stat );
329
330/*****************************************************************************************
331 * This function is used to activate / desactivate the trace for a thread
332 * identified by the <trdid> and <pid> arguments.
333 * It can be called by any other thread in the same process.
334 *****************************************************************************************
335 * @ operation  : operation type.
336 * @ pid        : process identifier.
337 * @ trdid      : thread identifier.
338 * @ returns O if success / returns -1 if failure.
339 ****************************************************************************************/
340int trace( unsigned int operation,
341           unsigned int pid, 
342           unsigned int trdid );
343
344
345#endif  // _STDIO_H_
Note: See TracBrowser for help on using the repository browser.