source: trunk/libs/mini-libc/unistd.h @ 603

Last change on this file since 603 was 589, checked in by alain, 6 years ago

Introduce a pause() syscall in mini-libc/unistd library.

File size: 11.9 KB
Line 
1/*
2 * unistd.h - User level <unistd> library definition.
3 *
4 * Author     Alain Greiner (2016,2017,2018)
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 _UNISTD_H_
25#define _UNISTD_H_
26
27/*****************************************************************************************
28 * This file defines the user level <unistd> library.
29 * All these functions make a system call to access the kernel structures.
30 * The user/kernel shared structures and mnemonics are defined in
31 * the <syscalls/shared_include/shared_unistd.h> file.
32 ****************************************************************************************/
33
34#include <shared_unistd.h>
35
36/*****************************************************************************************
37 * This function sets a timer to deliver the signal SIGALRM to the calling process,
38 * after the specified number of seconds.
39 * If an alarm has already been set with alarm() but has not been delivered,
40 * another call to alarm() will supersede the prior call.
41 * The request alarm(0) cancels the current alarm and the signal will not be delivered.
42 *****************************************************************************************
43 * @ seconds   : number of seconds.
44 * @ returns the amount of time left on the timer from a previous call to alarm().
45 *   If no alarm is currently set, the return value is 0.
46 ****************************************************************************************/
47unsigned alarm( unsigned seconds );
48
49/*****************************************************************************************
50 * This function change the current working directory in reference process descriptor.
51 *****************************************************************************************
52 * @ pathname   : pathname (can be relative or absolute).
53 * @ return 0 if success / returns -1 if failure.
54 ****************************************************************************************/
55int chdir( const char * pathname );
56
57/*****************************************************************************************
58 * This function release the memory allocated for the file descriptor identified by
59 * the <fd> argument, and remove the fd array_entry in all process descriptor copies.
60 *****************************************************************************************
61 * @ fd   : file descriptor index in fd_array.
62 * @ return 0 if success / returns -1 if failure.
63 ****************************************************************************************/
64int close( int fd );
65
66/*****************************************************************************************
67 * This function implement the "exec" system call on the user side.
68 * It creates, in the same cluster as the calling thread, a new process descriptor,
69 * and a new associated main thread descriptor, executing a new memory image defined
70 * by the <filename> argument. This new process inherit from the old process the PID
71 * and the PPID, as well as all open files (including the TXT).
72 * The old process descriptor, and all its threads are blocked, and marked for deletion.
73 * Therefore the exec syscall does not return to the calling thread in case of success.
74 * This function build an exec_info_t structure containing the new process arguments,
75 * as defined by the <arv> argument, and the new process environment variables,
76 * as defined by the <envp>  argument.
77 * TODO : the <argv> and <envp> arguments are not supported yet (both must be NULL).
78 *****************************************************************************************
79 * @ filename : string pointer on .elf filename (virtual pointer in user space)
80 * @ argv     : array of strings on process arguments (virtual pointers in user space)
81 * @ envp     : array of strings on environment variables (virtual pointers in user space)
82 * @ does not return if success / returns -1 if failure.
83 ****************************************************************************************/
84int execve( char  * filename,
85            char ** argv,
86            char ** envp );
87
88/*****************************************************************************************
89 * This function implement the "fork" system call on the user side.
90 * The calling process descriptor (parent process), and the associated thread descriptor
91 * are replicated in a - likely - remote cluster, that becomes the new process owner.
92 * The child process get a new PID is linked to the parent PID. The child process inherit
93 * from the parent process the memory image, and all open files (including the TXT).
94 * The child process becomes the TXT terminal owner.
95 * The target cluster depends on the "fork_user" flag and "fork_cxy" variable that can be
96 * stored in the calling thread descriptor by the specific fork_place() system call.
97 * If not, the kernel function makes a query to the DQDT to select the target cluster.
98 *****************************************************************************************
99 * @ if success, returns child process PID to parent, and return O to child.
100 * @ if failure, returns -1 to parent / no child process is created.
101 ****************************************************************************************/
102int fork( void );
103
104/*****************************************************************************************
105 * This function returns the pathname of the current working directory.
106 *****************************************************************************************
107 * buf     : buffer addres in user space.
108 * nbytes  : user buffer size in bytes.
109 * @ return 0 if success / returns -1 if failure.
110 ****************************************************************************************/
111int getcwd( char       * buf,
112            unsigned int nbytes );
113
114/*****************************************************************************************
115 * This function implements the "getpid" system call on the user side.
116 *****************************************************************************************
117 * @ returns the process PID for the calling thread process.
118 ****************************************************************************************/
119int getpid( void );
120
121/*****************************************************************************************
122 * This function test whether a file descriptor refers to a terminal.
123 *****************************************************************************************
124 * @ fd   : file descriptor index in fd_array.
125 * @ returns 1 if fd is an open file descriptor referring to a terminal / 0 otherwise.
126 ****************************************************************************************/
127int isatty( int fd );
128
129/*****************************************************************************************
130 * This function repositions the offset of the file descriptor identified by <fd>,
131 * according to the operation type defined by the <whence> argument.
132 *****************************************************************************************
133 * @ fd       : open file index in fd_array.
134 * @ offset   : used to compute new offset value.
135 * @ whence   : operation type (SEEK_SET / SEEK_CUR / SEEK_END)
136 * @ return 0 if success / returns -1 if failure.
137 ****************************************************************************************/
138int lseek( int           fd,
139           unsigned int  offset,
140           int           whence );
141
142/*****************************************************************************************
143 * This function stops the calling process until any signal is received.
144 *****************************************************************************************
145 * @ return 0 if success / returns -1 if failure.
146 ****************************************************************************************/
147int pause( void );
148
149/*****************************************************************************************
150 * This function creates in the calling thread cluster an unnamed pipe, and two
151 * (read and write) file descriptors to access this pipe. The calling function must pass
152 * the pointer on the fd[] array.
153 * TODO not implemented yet...
154 *****************************************************************************************
155 * @ fd[0] : [out] read only file descriptor index.
156 * @ fd[1] : [out] write only file descriptor index.
157 * @ return 0 if success / return -1 if failure.
158 ****************************************************************************************/
159int pipe( int fd[2] );
160
161/*****************************************************************************************
162 * This function read bytes from an open file identified by the <fd> file descriptor.
163 * This file can be a regular file or a character oriented device.
164 *****************************************************************************************
165 * @ fd       : open file index in fd_array.
166 * @ buf      : buffer virtual address in user space.
167 * @ count    : number of bytes.
168 * @ return number of bytes actually read if success / returns -1 if failure.
169 ****************************************************************************************/
170int read( int            fd,
171          void         * buf,
172          unsigned int   count );
173
174/*****************************************************************************************
175 * This function removes a directory file whose name is given by <pathname>.
176 * The directory must not have any entries other than `.' and `..'.
177 *****************************************************************************************
178 * @ pathname   : pathname (can be relative or absolute).
179 * @ return 0 if success / returns -1 if failure.
180 ****************************************************************************************/
181int rmdir( char * pathname ); 
182
183/*****************************************************************************************
184 * This function removes a directory entry identified by the <pathname> from the
185 * directory, and decrement the link count of the file referenced by the link.
186 * If the link count reduces to zero, and no process has the file open, then all resources
187 * associated with the file are released.  If one or more process have the file open when
188 * the last link is removed, the link is removed, but the removal of the file is delayed
189 * until all references to it have been closed.
190 *****************************************************************************************
191 * @ pathname   : pathname (can be relative or absolute).
192 * @ return 0 if success / returns -1 if failure.
193 ****************************************************************************************/
194int unlink( const char * pathname );
195
196/*****************************************************************************************
197 * This function writes bytes to an open file identified by the <fd> file descriptor.
198 * This file can be a regular file or character oriented device.
199 *****************************************************************************************
200 * @ fd       : open file index in fd_array.
201 * @ buf      : buffer virtual address in user space.
202 * @ count    : number of bytes.
203 * @ return number of bytes actually written if success / returns -1 if failure.
204 ****************************************************************************************/
205int write( int            fd,
206           const void   * buf,
207           unsigned int   count );
208
209#endif
Note: See TracBrowser for help on using the repository browser.