OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [newlib-1.18.0/] [newlib/] [libc/] [sys.tex] - Blame information for rev 829

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 207 jeremybenn
@c                                           -*- Texinfo -*-
2
@node Syscalls
3
@chapter System Calls
4
 
5
@cindex linking the C library
6
The C subroutine library depends on a handful of subroutine calls for
7
operating system services.  If you use the C library on a system that
8
complies with the POSIX.1 standard (also known as IEEE 1003.1), most of
9
these subroutines are supplied with your operating system.
10
 
11
If some of these subroutines are not provided with your system---in
12
the extreme case, if you are developing software for a ``bare board''
13
system, without an OS---you will at least need to provide do-nothing
14
stubs (or subroutines with minimal functionality) to allow your
15
programs to link with the subroutines in @code{libc.a}.
16
 
17
@menu
18
* Stubs::               Definitions for OS interface
19
* Reentrant Syscalls::  Reentrant covers for OS subroutines
20
@end menu
21
 
22
@node Stubs
23
@section Definitions for OS interface
24
@cindex stubs
25
 
26
@cindex subroutines for OS interface
27
@cindex OS interface subroutines
28
This is the complete set of system definitions (primarily subroutines)
29
required; the examples shown implement the minimal functionality
30
required to allow @code{libc} to link, and fail gracefully where OS
31
services are not available.
32
 
33
Graceful failure is permitted by returning an error code.  A minor
34
complication arises here: the C library must be compatible with
35
development environments that supply fully functional versions of these
36
subroutines.  Such environments usually return error codes in a global
37
@code{errno}.  However, the Red Hat newlib C library provides a @emph{macro}
38
definition for @code{errno} in the header file @file{errno.h}, as part
39
of its support for reentrant routines (@pxref{Reentrancy,,Reentrancy}).
40
 
41
@cindex @code{errno} global vs macro
42
The bridge between these two interpretations of @code{errno} is
43
straightforward: the C library routines with OS interface calls
44
capture the @code{errno} values returned globally, and record them in
45
the appropriate field of the reentrancy structure (so that you can query
46
them using the @code{errno} macro from @file{errno.h}).
47
 
48
This mechanism becomes visible when you write stub routines for OS
49
interfaces.   You must include @file{errno.h}, then disable the macro,
50
like this:
51
 
52
@example
53
#include <errno.h>
54
#undef errno
55
extern int errno;
56
@end example
57
 
58
@noindent
59
The examples in this chapter include this treatment of @code{errno}.
60
 
61
@ftable @code
62
@item _exit
63
Exit a program without cleaning up files.  If your system doesn't
64
provide this, it is best to avoid linking with subroutines that require
65
it (@code{exit}, @code{system}).
66
 
67
@item close
68
Close a file.  Minimal implementation:
69
 
70
@example
71
int close(int file) @{
72
  return -1;
73
@}
74
@end example
75
 
76
@item environ
77
A pointer to a list of environment variables and their values.  For a
78
minimal environment, this empty list is adequate:
79
 
80
@example
81
char *__env[1] = @{ 0 @};
82
char **environ = __env;
83
@end example
84
 
85
@item execve
86
Transfer control to a new process.  Minimal implementation (for a system
87
without processes):
88
 
89
@example
90
#include <errno.h>
91
#undef errno
92
extern int errno;
93
int execve(char *name, char **argv, char **env) @{
94
  errno = ENOMEM;
95
  return -1;
96
@}
97
@end example
98
 
99
@item fork
100
Create a new process.  Minimal implementation (for a system without processes):
101
 
102
@example
103
#include <errno.h>
104
#undef errno
105
extern int errno;
106
int fork(void) @{
107
  errno = EAGAIN;
108
  return -1;
109
@}
110
@end example
111
 
112
@item fstat
113
Status of an open file.  For consistency with other minimal
114
implementations in these examples, all files are regarded as character
115
special devices.  The @file{sys/stat.h} header file required is
116
distributed in the @file{include} subdirectory for this C library.
117
 
118
@example
119
#include <sys/stat.h>
120
int fstat(int file, struct stat *st) @{
121
  st->st_mode = S_IFCHR;
122
  return 0;
123
@}
124
@end example
125
 
126
@item getpid
127
Process-ID; this is sometimes used to generate strings unlikely to
128
conflict with other processes.  Minimal implementation, for a system
129
without processes:
130
 
131
@example
132
int getpid(void) @{
133
  return 1;
134
@}
135
@end example
136
 
137
@item isatty
138
Query whether output stream is a terminal.   For consistency with the
139
other minimal implementations, which only support output to
140
@code{stdout}, this minimal implementation is suggested:
141
 
142
@example
143
int isatty(int file) @{
144
  return 1;
145
@}
146
@end example
147
 
148
@item kill
149
Send a signal.  Minimal implementation:
150
 
151
@example
152
#include <errno.h>
153
#undef errno
154
extern int errno;
155
int kill(int pid, int sig) @{
156
  errno = EINVAL;
157
  return -1;
158
@}
159
@end example
160
 
161
@item link
162
Establish a new name for an existing file.  Minimal implementation:
163
 
164
@example
165
#include <errno.h>
166
#undef errno
167
extern int errno;
168
int link(char *old, char *new) @{
169
  errno = EMLINK;
170
  return -1;
171
@}
172
@end example
173
 
174
@item lseek
175
Set position in a file.  Minimal implementation:
176
 
177
@example
178
int lseek(int file, int ptr, int dir) @{
179
  return 0;
180
@}
181
@end example
182
 
183
@item open
184
Open a file.  Minimal implementation:
185
 
186
@example
187
int open(const char *name, int flags, int mode) @{
188
  return -1;
189
@}
190
@end example
191
 
192
@item read
193
Read from a file.  Minimal implementation:
194
 
195
@example
196
int read(int file, char *ptr, int len) @{
197
  return 0;
198
@}
199
@end example
200
 
201
@item sbrk
202
Increase program data space.  As @code{malloc} and related functions
203
depend on this, it is useful to have a working implementation.  The
204
following suffices for a standalone system; it exploits the symbol
205
@code{_end} automatically defined by the GNU linker.
206
 
207
@example
208
@group
209
caddr_t sbrk(int incr) @{
210
  extern char _end;             /* @r{Defined by the linker} */
211
  static char *heap_end;
212
  char *prev_heap_end;
213
 
214
  if (heap_end == 0) @{
215
    heap_end = &_end;
216
  @}
217
  prev_heap_end = heap_end;
218
  if (heap_end + incr > stack_ptr) @{
219
    write (1, "Heap and stack collision\n", 25);
220
    abort ();
221
  @}
222
 
223
  heap_end += incr;
224
  return (caddr_t) prev_heap_end;
225
@}
226
@end group
227
@end example
228
 
229
@item stat
230
Status of a file (by name).  Minimal implementation:
231
 
232
@example
233
int stat(char *file, struct stat *st) @{
234
  st->st_mode = S_IFCHR;
235
  return 0;
236
@}
237
@end example
238
 
239
@item times
240
Timing information for current process.  Minimal implementation:
241
 
242
@example
243
int times(struct tms *buf) @{
244
  return -1;
245
@}
246
@end example
247
 
248
@item unlink
249
Remove a file's directory entry.  Minimal implementation:
250
 
251
@example
252
#include <errno.h>
253
#undef errno
254
extern int errno;
255
int unlink(char *name) @{
256
  errno = ENOENT;
257
  return -1;
258
@}
259
@end example
260
 
261
@item wait
262
Wait for a child process.  Minimal implementation:
263
@example
264
#include <errno.h>
265
#undef errno
266
extern int errno;
267
int wait(int *status) @{
268
  errno = ECHILD;
269
  return -1;
270
@}
271
@end example
272
 
273
@item write
274
Write to a file.  @file{libc} subroutines will use this
275
system routine for output to all files, @emph{including}
276
@code{stdout}---so if you need to generate any output, for example to a
277
serial port for debugging, you should make your minimal @code{write}
278
capable of doing this.  The following minimal implementation is an
279
incomplete example; it relies on a @code{outbyte} subroutine (not
280
shown; typically, you must write this in assembler from examples
281
provided by your hardware manufacturer) to actually perform the output.
282
 
283
@example
284
@group
285
int write(int file, char *ptr, int len) @{
286
  int todo;
287
 
288
  for (todo = 0; todo < len; todo++) @{
289
    outbyte (*ptr++);
290
  @}
291
  return len;
292
@}
293
@end group
294
@end example
295
 
296
@end ftable
297
 
298
@page
299
@node Reentrant Syscalls
300
@section Reentrant covers for OS subroutines
301
 
302
Since the system subroutines are used by other library routines that
303
require reentrancy, @file{libc.a} provides cover routines (for example,
304
the reentrant version of @code{fork} is @code{_fork_r}).  These cover
305
routines are consistent with the other reentrant subroutines in this
306
library, and achieve reentrancy by using a reserved global data block
307
(@pxref{Reentrancy,,Reentrancy}).
308
 
309
@c FIXME!!! The following ignored text specifies how this section ought
310
@c to work;  however, both standalone info and Emacs info mode fail when
311
@c confronted with nodes beginning `_' as of 24may93.  Restore when Info
312
@c readers fixed!
313
@ignore
314
@menu
315
* _open_r::     Reentrant version of open
316
* _close_r::    Reentrant version of close
317
* _lseek_r::    Reentrant version of lseek
318
* _read_r::     Reentrant version of read
319
* _write_r::    Reentrant version of write
320
* _link_r::     Reentrant version of link
321
* _unlink_r::   Reentrant version of unlink
322
* _stat_r::     Reentrant version of stat
323
* _fstat_r::    Reentrant version of fstat
324
* _sbrk_r::     Reentrant version of sbrk
325
* _fork_r::     Reentrant version of fork
326
* _wait_r::     Reentrant version of wait
327
@end menu
328
 
329
@down
330
@include reent/filer.def
331
@include reent/execr.def
332
@include reent/statr.def
333
@include reent/fstatr.def
334
@include reent/linkr.def
335
@include reent/unlinkr.def
336
@include reent/sbrkr.def
337
@up
338
@end ignore
339
 
340
@ftable @code
341
@item _open_r
342
A reentrant version of @code{open}.  It takes a pointer
343
to the global data block, which holds @code{errno}.
344
 
345
@example
346
int _open_r(void *@var{reent},
347
    const char *@var{file}, int @var{flags}, int @var{mode});
348
@end example
349
 
350
@ifset STDIO64
351
@item _open64_r
352
A reentrant version of @code{open64}.  It takes a pointer
353
to the global data block, which holds @code{errno}.
354
 
355
@example
356
int _open64_r(void *@var{reent},
357
    const char *@var{file}, int @var{flags}, int @var{mode});
358
@end example
359
@end ifset
360
 
361
@item _close_r
362
A reentrant version of @code{close}.  It takes a pointer to the global
363
data block, which holds @code{errno}.
364
 
365
@example
366
int _close_r(void *@var{reent}, int @var{fd});
367
@end example
368
 
369
@item _lseek_r
370
A reentrant version of @code{lseek}.  It takes a pointer to the global
371
data block, which holds @code{errno}.
372
 
373
@example
374
off_t _lseek_r(void *@var{reent},
375
    int @var{fd}, off_t @var{pos}, int @var{whence});
376
@end example
377
 
378
@ifset STDIO64
379
@item _lseek64_r
380
A reentrant version of @code{lseek64}.  It takes a pointer to the global
381
data block, which holds @code{errno}.
382
 
383
@example
384
off_t _lseek64_r(void *@var{reent},
385
    int @var{fd}, off_t @var{pos}, int @var{whence});
386
@end example
387
@end ifset
388
 
389
@item _read_r
390
A reentrant version of @code{read}.  It takes a pointer to the global
391
data block, which holds @code{errno}.
392
 
393
@example
394
long _read_r(void *@var{reent},
395
    int @var{fd}, void *@var{buf}, size_t @var{cnt});
396
@end example
397
 
398
@item _write_r
399
A reentrant version of @code{write}.  It takes a pointer to the global
400
data block, which holds @code{errno}.
401
 
402
@example
403
long _write_r(void *@var{reent},
404
    int @var{fd}, const void *@var{buf}, size_t @var{cnt});
405
@end example
406
 
407
@item _fork_r
408
A reentrant version of @code{fork}.  It takes a pointer to the global
409
data block, which holds @code{errno}.
410
 
411
@example
412
int _fork_r(void *@var{reent});
413
@end example
414
 
415
@item _wait_r
416
A reentrant version of @code{wait}.  It takes a pointer to the global
417
data block, which holds @code{errno}.
418
 
419
@example
420
int _wait_r(void *@var{reent}, int *@var{status});
421
@end example
422
 
423
@item _stat_r
424
A reentrant version of @code{stat}.  It takes a pointer to the global
425
data block, which holds @code{errno}.
426
 
427
@example
428
int _stat_r(void *@var{reent},
429
    const char *@var{file}, struct stat *@var{pstat});
430
@end example
431
 
432
@item _fstat_r
433
A reentrant version of @code{fstat}.  It takes a pointer to the global
434
data block, which holds @code{errno}.
435
 
436
@example
437
int _fstat_r(void *@var{reent},
438
    int @var{fd}, struct stat *@var{pstat});
439
@end example
440
 
441
@ifset STDIO64
442
@item _fstat64_r
443
A reentrant version of @code{fstat64}.  It takes a pointer to the global
444
data block, which holds @code{errno}.
445
 
446
@example
447
int _fstat64_r(void *@var{reent},
448
    int @var{fd}, struct stat *@var{pstat});
449
@end example
450
@end ifset
451
 
452
@item _link_r
453
A reentrant version of @code{link}.  It takes a pointer to the global
454
data block, which holds @code{errno}.
455
 
456
@example
457
int _link_r(void *@var{reent},
458
    const char *@var{old}, const char *@var{new});
459
@end example
460
 
461
@item _unlink_r
462
A reentrant version of @code{unlink}.  It takes a pointer to the global
463
data block, which holds @code{errno}.
464
 
465
@example
466
int _unlink_r(void *@var{reent}, const char *@var{file});
467
@end example
468
 
469
@item _sbrk_r
470
A reentrant version of @code{sbrk}.  It takes a pointer to the global
471
data block, which holds @code{errno}.
472
 
473
@example
474
char *_sbrk_r(void *@var{reent}, size_t @var{incr});
475
@end example
476
@end ftable

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.