diff options
author | Joel Sherrill <joel.sherrill@OARcorp.com> | 1998-11-19 16:06:46 +0000 |
---|---|---|
committer | Joel Sherrill <joel.sherrill@OARcorp.com> | 1998-11-19 16:06:46 +0000 |
commit | c4dddee3f5d2714e0a5cb9a137cb01e7cf2adf2a (patch) | |
tree | 4ff7c2624fe2f3d21024fd67d15dbb78a03e934e | |
parent | New files (diff) | |
download | rtems-c4dddee3f5d2714e0a5cb9a137cb01e7cf2adf2a.tar.bz2 |
Major update/merge of POSIX manual.
-rw-r--r-- | doc/posix_users/base.texi | 98 | ||||
-rw-r--r-- | doc/posix_users/clock.t (renamed from doc/posix_users/clock.texi) | 130 | ||||
-rw-r--r-- | doc/posix_users/cond.t (renamed from doc/posix_users/cond.texi) | 73 | ||||
-rw-r--r-- | doc/posix_users/cspecific.t | 623 | ||||
-rw-r--r-- | doc/posix_users/device.t | 465 | ||||
-rw-r--r-- | doc/posix_users/files.t | 2088 | ||||
-rw-r--r-- | doc/posix_users/io.t | 1085 | ||||
-rw-r--r-- | doc/posix_users/key.t (renamed from doc/posix_users/key.texi) | 49 | ||||
-rw-r--r-- | doc/posix_users/memorymgmt.t | 315 | ||||
-rw-r--r-- | doc/posix_users/message.t | 259 | ||||
-rw-r--r-- | doc/posix_users/mutex.t (renamed from doc/posix_users/mutex.texi) | 97 | ||||
-rw-r--r-- | doc/posix_users/preface.texi | 24 | ||||
-rw-r--r-- | doc/posix_users/procenv.t | 654 | ||||
-rw-r--r-- | doc/posix_users/process.t | 414 | ||||
-rw-r--r-- | doc/posix_users/sched.t (renamed from doc/posix_users/sched.texi) | 61 | ||||
-rw-r--r-- | doc/posix_users/semaphores.t | 287 | ||||
-rw-r--r-- | doc/posix_users/signal.t (renamed from doc/posix_users/signal.texi) | 359 | ||||
-rw-r--r-- | doc/posix_users/systemdb.t | 259 | ||||
-rw-r--r-- | doc/posix_users/thread.t (renamed from doc/posix_users/thread.texi) | 141 |
19 files changed, 6740 insertions, 741 deletions
diff --git a/doc/posix_users/base.texi b/doc/posix_users/base.texi deleted file mode 100644 index 34d1e75af2..0000000000 --- a/doc/posix_users/base.texi +++ /dev/null @@ -1,98 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-1998. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@ifinfo -@node Mutex Manager, Mutex Manager Introduction, Preface, Top -@end ifinfo -@chapter Mutex Manager -@ifinfo -@menu -* Mutex Manager Introduction:: -* Mutex Manager Background:: -* Mutex Manager Operations:: -* Mutex Manager Directives:: -@end menu -@end ifinfo - -@ifinfo -@node Mutex Manager Introduction, Mutex Manager Background, Mutex Manager, Mutex Manager -@end ifinfo -@section Introduction - -The mutex manager ... - -The directives provided by the mutex manager are: - -@itemize @bullet -@item @code{sigaddset} - -@item @code{sigdelset} - -@item @code{sigfillset} - -@item @code{sigismember} - -@item @code{sigemptyset} - -@item @code{sigaction} - -@item @code{pthread_kill} - -@item @code{pthread_sigmask} - -@item @code{kill} - -@item @code{sigwait} - -@end itemize - -@ifinfo -@node Mutex Manager Background, Mutex Manager Operations, Mutex Manager Introduction, Mutex Manager -@end ifinfo -@section Background - -@ifinfo -@node Mutex Manager Operations, Mutex Manager Directives, Mutex Manager Background, Mutex Manager -@end ifinfo -@section Operations - -@ifinfo -@node Mutex Manager Directives, sigaddset, Mutex Manager Operations, Mutex Manager -@end ifinfo -@section Directives -@ifinfo -@menu -* sigaddset:: -* sigdelset:: -* sigfillset:: -* sigismember:: -* sigemptyset:: -* sigaction:: -* pthread_kill:: -* pthread_sigmask:: -* kill:: -* sigwait:: -@end menu -@end ifinfo - -This section details the mutex manager's directives. -A subsection is dedicated to each of this manager's directives -and describes the calling sequence, related constants, usage, -and status codes. - -@page -@ifinfo -@node sigaddset, sigdelset, Mutex Manager Directives, Mutex Manager Directives -@end ifinfo -@subsection sigaddset - -@subheading CALLING SEQUENCE: - -@example -int sigaddset( - sigset_t *set, - int signo -); -@end example - -@subheading STATUS CODES: - -@subheading DESCRIPTION: - -@subheading NOTES: - diff --git a/doc/posix_users/clock.texi b/doc/posix_users/clock.t index d2f7e1e492..7c05acd671 100644 --- a/doc/posix_users/clock.texi +++ b/doc/posix_users/clock.t @@ -6,22 +6,8 @@ @c $Id$ @c -@ifinfo -@node Clock Manager, Clock Manager Introduction, pthread_getspecific, Top -@end ifinfo @chapter Clock Manager -@ifinfo -@menu -* Clock Manager Introduction:: -* Clock Manager Background:: -* Clock Manager Operations:: -* Clock Manager Directives:: -@end menu -@end ifinfo - -@ifinfo -@node Clock Manager Introduction, Clock Manager Background, Clock Manager, Clock Manager -@end ifinfo + @section Introduction The clock manager ... @@ -32,45 +18,28 @@ The directives provided by the clock manager are: @item @code{clock_gettime} - @item @code{clock_settime} - @item @code{clock_getres} - +@item @code{sleep} - Delay Process Execution @item @code{nanosleep} - -@item @code{time} - +@item @code{gettimeofday} - Get the Time of Day +@item @code{time} - Get time in seconds @end itemize -@ifinfo -@node Clock Manager Background, Clock Manager Operations, Clock Manager Introduction, Clock Manager -@end ifinfo @section Background -@ifinfo -@node Clock Manager Operations, Clock Manager Directives, Clock Manager Background, Clock Manager -@end ifinfo +There is currently no text in this section. + @section Operations -@ifinfo -@node Clock Manager Directives, clock_gettime, Clock Manager Operations, Clock Manager -@end ifinfo +There is currently no text in this section. + @section Directives -@ifinfo -@menu -* clock_gettime:: -* clock_settime:: -* clock_getres:: -* sleep:: -* nanosleep:: -* time:: -@end menu -@end ifinfo This section details the clock manager's directives. A subsection is dedicated to each of this manager's directives and describes the calling sequence, related constants, usage, and status codes. -@page -@ifinfo -@node clock_gettime, clock_settime, Clock Manager Directives, Clock Manager Directives -@end ifinfo -@subsection clock_gettime +@subsection clock_gettime - @subheading CALLING SEQUENCE: @@ -99,11 +68,10 @@ The clock_id specified is invalid. @subheading NOTES: +NONE + @page -@ifinfo -@node clock_settime, clock_getres, clock_gettime, Clock Manager Directives -@end ifinfo -@subsection clock_settime +@subsection clock_settime - @subheading CALLING SEQUENCE: @@ -135,12 +103,11 @@ The contents of the tp structure are invalid. @subheading DESCRIPTION: @subheading NOTES: + +NONE @page -@ifinfo -@node clock_getres, sleep, clock_settime, Clock Manager Directives -@end ifinfo -@subsection clock_getres +@subsection clock_getres - @subheading CALLING SEQUENCE: @@ -173,10 +140,7 @@ The clock_id specified is invalid. If res is NULL, then the resolution is not returned. @page -@ifinfo -@node sleep, nanosleep, clock_getres, Clock Manager Directives -@end ifinfo -@subsection sleep +@subsection sleep - Delay Process Execution @subheading CALLING SEQUENCE: @@ -194,15 +158,15 @@ This routine returns the number of unslept seconds. @subheading DESCRIPTION: +The @code{sleep()} function delays the calling thread by the specified +number of @code{seconds}. + @subheading NOTES: This call is interruptible by a signal. @page -@ifinfo -@node nanosleep, time, sleep, Clock Manager Directives -@end ifinfo -@subsection nanosleep +@subsection nanosleep - @subheading CALLING SEQUENCE: @@ -239,10 +203,48 @@ field. This call is interruptible by a signal. @page -@ifinfo -@node time, Scheduler Manager, nanosleep, Clock Manager Directives -@end ifinfo -@subsection nanosleep +@subsection gettimeofday - Get the Time of Day + +@subheading CALLING SEQUENCE: + +@example +#include <sys/time.h> +#include <unistd.h> + +int gettimeofday( + struct timeval *tp, + struct timezone *tzp +); +@end example + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets @code{errno} as appropriate. + +@table @b +@item EPERM +@code{settimeofdat} is called by someone other than the superuser. + +@item EINVAL +Timezone (or something else) is invalid. + +@item EFAULT +One of @code{tv} or @code{tz} pointed outside your accessible address +space + +@end table + +@subheading DESCRIPTION: + +This routine returns the current time of day in the @code{tp} structure. + +@subheading NOTES: + +Currently, the timezone information is not supported. The @code{tzp} +argument is ignored. + +@page +@subsection time - Get time in seconds @subheading CALLING SEQUENCE: @@ -259,6 +261,14 @@ int time( This routine returns the number of seconds since the Epoch. @subheading DESCRIPTION: + +@code{time} returns the time since 00:00:00 GMT, January 1, 1970, +measured in seconds + +If @code{tloc} in non null, the return value is also stored in the +memory pointed to by @code{t}. @subheading NOTES: + +NONE diff --git a/doc/posix_users/cond.texi b/doc/posix_users/cond.t index e9c8abf460..4c381a6864 100644 --- a/doc/posix_users/cond.texi +++ b/doc/posix_users/cond.t @@ -6,22 +6,8 @@ @c $Id$ @c -@ifinfo -@node Condition Variable Manager, Condition Variable Manager Introduction, pthread_mutex_getprioceiling, Top -@end ifinfo @chapter Condition Variable Manager -@ifinfo -@menu -* Condition Variable Manager Introduction:: -* Condition Variable Manager Background:: -* Condition Variable Manager Operations:: -* Condition Variable Manager Directives:: -@end menu -@end ifinfo - -@ifinfo -@node Condition Variable Manager Introduction, Condition Variable Manager Background, Condition Variable Manager, Condition Variable Manager -@end ifinfo + @section Introduction The condition variable manager ... @@ -41,34 +27,15 @@ The directives provided by the condition variable manager are: @item @code{pthread_cond_timedwait} - @end itemize -@ifinfo -@node Condition Variable Manager Background, Condition Variable Manager Operations, Condition Variable Manager Introduction, Condition Variable Manager -@end ifinfo @section Background -@ifinfo -@node Condition Variable Manager Operations, Condition Variable Manager Directives, Condition Variable Manager Background, Condition Variable Manager -@end ifinfo +There is currently no text in this section. + @section Operations -@ifinfo -@node Condition Variable Manager Directives, pthread_condattr_init, Condition Variable Manager Operations, Condition Variable Manager -@end ifinfo +There is currently no text in this section. + @section Directives -@ifinfo -@menu -* pthread_condattr_init:: -* pthread_condattr_destroy:: -* pthread_condattr_setpshared:: -* pthread_condattr_getpshared:: -* pthread_cond_init:: -* pthread_cond_destroy:: -* pthread_cond_signal:: -* pthread_cond_broadcast:: -* pthread_cond_wait:: -* pthread_cond_timedwait:: -@end menu -@end ifinfo This section details the condition variable manager's directives. A subsection is dedicated to each of this manager's directives @@ -76,9 +43,6 @@ and describes the calling sequence, related constants, usage, and status codes. @page -@ifinfo -@node pthread_condattr_init, pthread_condattr_destroy, Condition Variable Manager Directives, Condition Variable Manager Directives -@end ifinfo @subsection pthread_condattr_init @subheading CALLING SEQUENCE: @@ -104,9 +68,6 @@ attributes object. @subheading NOTES: @page -@ifinfo -@node pthread_condattr_destroy, pthread_condattr_setpshared, pthread_condattr_init, Condition Variable Manager Directives -@end ifinfo @subsection pthread_condattr_destroy @subheading CALLING SEQUENCE: @@ -131,9 +92,6 @@ The attribute object specified is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_condattr_setpshared, pthread_condattr_getpshared, pthread_condattr_destroy, Condition Variable Manager Directives -@end ifinfo @subsection pthread_condattr_setpshared @subheading CALLING SEQUENCE: @@ -160,9 +118,6 @@ Invalid argument passed. @subheading NOTES: @page -@ifinfo -@node pthread_condattr_getpshared, pthread_cond_init, pthread_condattr_setpshared, Condition Variable Manager Directives -@end ifinfo @subsection pthread_condattr_getpshared @subheading CALLING SEQUENCE: @@ -190,9 +145,6 @@ Invalid argument passed. @page -@ifinfo -@node pthread_cond_init, pthread_cond_destroy, pthread_condattr_getpshared, Condition Variable Manager Directives -@end ifinfo @subsection pthread_cond_init @subheading CALLING SEQUENCE: @@ -228,9 +180,6 @@ The specified attribute value is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_cond_destroy, pthread_cond_signal, pthread_cond_init, Condition Variable Manager Directives -@end ifinfo @subsection pthread_cond_destroy @subheading CALLING SEQUENCE: @@ -258,9 +207,6 @@ The specified condition variable is currently in use. @subheading NOTES: @page -@ifinfo -@node pthread_cond_signal, pthread_cond_broadcast, pthread_cond_destroy, Condition Variable Manager Directives -@end ifinfo @subsection pthread_cond_signal @subheading CALLING SEQUENCE: @@ -288,9 +234,6 @@ This routine should not be invoked from a handler from an asynchronous signal handler or an interrupt service routine. @page -@ifinfo -@node pthread_cond_broadcast, pthread_cond_wait, pthread_cond_signal, Condition Variable Manager Directives -@end ifinfo @subsection pthread_cond_broadcast @subheading CALLING SEQUENCE: @@ -318,9 +261,6 @@ This routine should not be invoked from a handler from an asynchronous signal handler or an interrupt service routine. @page -@ifinfo -@node pthread_cond_wait, pthread_cond_timedwait, pthread_cond_broadcast, Condition Variable Manager Directives -@end ifinfo @subsection pthread_cond_wait @subheading CALLING SEQUENCE: @@ -349,9 +289,6 @@ the mutex was not owned by the current thread at the time of the call. @subheading NOTES: @page -@ifinfo -@node pthread_cond_timedwait, Key Manager, pthread_cond_wait, Condition Variable Manager Directives -@end ifinfo @subsection pthread_cond_timedwait @subheading CALLING SEQUENCE: diff --git a/doc/posix_users/cspecific.t b/doc/posix_users/cspecific.t new file mode 100644 index 0000000000..5e2de31617 --- /dev/null +++ b/doc/posix_users/cspecific.t @@ -0,0 +1,623 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Language-Specific Services for the C Programming Language Manager + +@section Introduction + +The +language-specific services for the C programming language manager is ... + +The directives provided by the language-specific services for the C programming language manager are: + +@itemize @bullet +@item @code{setlocale} - +@item @code{fileno} - +@item @code{fdopen} - +@item @code{flcokfile} - +@item @code{ftrylockfile} - +@item @code{funlockfile} - +@item @code{getc_unlocked} - +@item @code{getchar_unlocked} - +@item @code{putc_unlocked} - +@item @code{putchar_unlocked} - +@item @code{setjmp} - +@item @code{longjmp} - +@item @code{sigsetjmp} - +@item @code{siglongjmp} - +@item @code{tzset} - +@item @code{strtok_r} - +@item @code{asctime_r} - +@item @code{ctime_r} - +@item @code{gmtime_r} - +@item @code{localtime_r} - +@item @code{rand_r} - +@end itemize + +@section Background + +There is currently no text in this section. + +@section Operations + +There is currently no text in this section. + +@section Directives + +This section details the language-specific services for the C programming language manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection setlocale - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int setlocale( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection fileno - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int fileno( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection fdopen - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int fdopen( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection flcokfile - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int flcokfile( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection ftrylockfile - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int ftrylockfile( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection funlockfile - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int funlockfile( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getc_unlocked - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getc_unlocked( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getchar_unlocked - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getchar_unlocked( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection putc_unlocked - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int putc_unlocked( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection putchar_unlocked - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int putchar_unlocked( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection setjmp - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int setjmp( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection longjmp - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int longjmp( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection sigsetjmp - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sigsetjmp( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection siglongjmp - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int siglongjmp( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection tzset - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int tzset( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection strtok_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int strtok_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection asctime_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int asctime_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection ctime_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int ctime_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection gmtime_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int gmtime_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection localtime_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int localtime_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection rand_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int rand_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/device.t b/doc/posix_users/device.t new file mode 100644 index 0000000000..05ef101fec --- /dev/null +++ b/doc/posix_users/device.t @@ -0,0 +1,465 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Device- and Class- Specific Functions Manager + +@section Introduction + +The device- and class- specific functions manager is ... + +The directives provided by the device- and class- specific functions +manager are: + +@itemize @bullet +@item @code{cfgetispeed} - Reads terminal input baud rate +@item @code{cfgetospeed} - Reads terminal output baud rate +@item @code{cfsetispeed} - Sets terminal input baud rate +@item @code{cfsetospeed} - Set terminal output baud rate +@item @code{tcgetattr} - Gets terminal attributes +@item @code{tcsetattr} - Set terminal attributes +@item @code{tcsendbreak} - Sends a break to a terminal +@item @code{tcdrain} - Waits for all output to be transmitted to the terminal +@item @code{tcflush} - Discards terminal data +@item @code{tcflow} - Suspends/restarts terminal output +@item @code{tcgetpgrp} - Gets foreground process group ID +@item @code{tcsetpgrp} - Sets foreground process group ID +@end itemize + +@section Background + +There is currently no text in this section. + +@section Operations + +There is currently no text in this section. + +@section Directives + +This section details the device- and class- specific functions manager's +directives. A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection cfgetispeed - Reads terminal input baud rate + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <termios.h> + +int cfgetispeed( + const struct termios *p +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +The @code{cfgetispeed()} function returns a code for baud rate. + +@subheading DESCRIPTION: + +The @code{cfsetispeed()} function stores a code for the terminal speed +stored in a struct termios. The codes are defined in @code{<termios.h>} +by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200, +B1800, B2400, B4800, B9600, B19200, and B38400. + +The @code{cfsetispeed()} function does not do anything to the hardware. +It merely stores a value for use by @code{tcsetattr()}. + +@subheading NOTES: + +Baud rates are defined by symbols, such as B110, B1200, B2400. The actual +number returned for any given speed may change from system to system. + +@page +@subsection cfgetospeed - Reads terminal output baud rate + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <termios.h> + +int cfgetospeed( + const struct termios *p +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +The @code{cfgetospeed()} function returns the termios code for the baud rate. + +@subheading DESCRIPTION: + +The @code{cfgetospeed()} function returns a code for the terminal speed +stored in a @code{struct termios}. The codes are defined in @code{<termios.h>} +by the macros BO, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800, +B2400, B4800, B9600, B19200, and B38400. + +The @code{cfgetospeed()} function does not do anything to the hardware. +It merely returns the value stored by a previous call to @code{tcgetattr()}. + +@subheading NOTES: + +Baud rates are defined by symbols, such as B110, B1200, B2400. The actual +number returned for any given speed may change from system to system. + +@page +@subsection cfsetispeed - Sets terminal input baud rate + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <termios.h> + +int cfsetispeed( + struct termios *p, + speed_t speed +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +The @code{cfsetispeed()} function returns a zero when successful and +returns -1 when an error occurs. + +@subheading DESCRIPTION: + +The @code{cfsetispeed()} function stores a code for the terminal speed +stored in a struct termios. The codes are defined in @code{<termios.h>} +by the macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, +B1800, B2400, B4800, B9600, B19200, and B38400. + +@subheading NOTES: + +This function merely stores a value in the @code{termios} structure. It +does not change the terminal speed until a @code{tcsetattr()} is done. +It does not detect impossible terminal speeds. + +@page +@subsection cfsetospeed - Sets terminal output baud rate + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <termios.h> + +int cfsetospeed( + struct termios *p, + speed_t speed +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +The @code{cfsetospeed()} function returns a zero when successful and +returns -1 when an error occurs. + + +@subheading DESCRIPTION: + +The @code{cfsetospeed()} function stores a code for the terminal speed stored +in a struct @code{termios}. The codes are defiined in @code{<termios.h>} by the +macros B0, B50, B75, B110, B134, B150, B200, B300, B600, B1200, B1800, B2400, +B4800, B9600, B19200, and B38400. + +The @code{cfsetospeed()} function does not do anything to the hardware. It +merely stores a value for use by @code{tcsetattr()}. + +@subheading NOTES: + +This function merely stores a value in the @code{termios} structure. +It does not change the terminal speed until a @code{tcsetattr()} is done. +It does not detect impossible terminal speeds. + +@page +@subsection tcgetattr - Gets terminal attributes + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <termios.h> +#include <unistd.h> + +int tcgetattr( + int fildes, + struct termios *p +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EBADF +Invalid file descriptor + +@item ENOOTY +Terminal control function attempted for a file that is not a terminal. +@end table + +@subheading DESCRIPTION: + +The @code{tcgetattr()} gets the parameters associated with the terminal +referred to by @code{fildes} and stores them into the @code{termios()} +structure pointed to by @code{termios_p}. + +@subheading NOTES: + +NONE + +@page +@subsection tcsetattr - Set terminal attributes + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <termios.h> +#include <unistd.h> + +int tcsetattr( + int fildes, + int options, + const struct termios *tp +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection tcsendbreak - Sends a break to a terminal + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int tcsendbreak( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection tcdrain - Waits for all output to be transmitted to the terminal. + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <termios.h> +#include <unistd.h> + +int tcdrain( + int fildes +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EBADF +Invalid file descriptor + +@item EINTR +Function was interrupted by a signal + +@item ENOTTY +Terminal control function attempted for a file that is not a terminal. + +@end table + +@subheading DESCRIPTION: + +The @code{tcdrain()} function waits until all output written to +@code{fildes} has been transmitted. + +@subheading NOTES: + +NONE + +@page +@subsection tcflush - Discards terminal data + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int tcflush( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection tcflow - Suspends/restarts terminal output. + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int tcflow( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection tcgetpgrp - Gets foreground process group ID + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int tcgetpgrp( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection tcsetpgrp - Sets foreground process group ID + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int tcsetpgrp( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + + diff --git a/doc/posix_users/files.t b/doc/posix_users/files.t new file mode 100644 index 0000000000..1a116cc3fa --- /dev/null +++ b/doc/posix_users/files.t @@ -0,0 +1,2088 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Files and Directories Manager + +@section Introduction + +The files and directories manager is ... + +The directives provided by the files and directories manager are: + +@itemize @bullet +@item @code{opendir} - Open a Directory +@item @code{readdir} - Reads a directory +@item @code{rewinddir} - Resets the @code{readdir()} pointer +@item @code{scandir} - Scan a directory for matching entries +@item @code{telldir} - Return current location in directory stream +@item @code{closedir} - Ends directory read operation +@item @code{getdents} - Get directory entries +@item @code{chdir} - Changes the current working directory +@item @code{getcwd} - Gets current working directory +@item @code{open} - Opens a file +@item @code{creat} - Create a new file or rewrite an existing one +@item @code{umask} - Sets a file creation mask +@item @code{link} - Creates a link to a file +@item @code{symlink} - Creates a symbolic link to a file +@item @code{readlink} - Obtain the name of the link destination +@item @code{mkdir} - Makes a directory +@item @code{mkfifo} - Makes a FIFO special file +@item @code{unlink} - Removes a directory entry +@item @code{rmdir} - Delete a directory +@item @code{rename} - Renames a file +@item @code{stat} - Gets information about a file. +@item @code{fstat} - Gets file status +@item @code{access} - Check user's permissions for a file. +@item @code{chmod} - Changes file mode +@item @code{fchmod} - Changes permissions of a file +@item @code{chown} - Changes the owner and/ or group of a file +@item @code{utime} - Change access and/or modification times of an inode +@item @code{ftruncate} - Truncate a file to a specified length +@item @code{truncate} - Truncate a file to a specified length +@item @code{pathconf} - Gets configuration values for files +@item @code{fpathconf} - Get configuration values for files +@item @code{mknod} - Create a directory +@end itemize + +@section Background + +There is currently no text in this section. + +@section Operations + +There is currently no text in this section. + +@section Directives + +This section details the files and directories manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection opendir - Open a Directory + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <dirent.h> + +int opendir( + const char *dirname +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Search permission was denied on a component of the path +prefix of @code{dirname}, or read permission is denied + +@item EMFILE +Too many file descriptors in use by process + +@item ENFILE +Too many files are currently open in the system. + +@item ENOENT +Directory does not exist, or @code{name} is an empty string. + +@item ENOMEM +Insufficient memory to complete the operation. + +@item ENOTDIR +@code{name} is not a directory. + +@end table + +@subheading DESCRIPTION: + +This routine opens a directory stream corresponding to the +directory specified by the @code{dirname} argument. The +directory stream is positioned at the first entry. + +@subheading NOTES: + +The routine is implemented in Cygnus newlib. + +@page +@subsection readdir - Reads a directory + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <dirent.h> + +int readdir( + DIR *dirp +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EBADF +Invalid file descriptor + +@end table + +@subheading DESCRIPTION: + +The @code{readdir()} function returns a pointer to a structure @code{dirent} +representing the next directory entry from the directory stream pointed to +by @code{dirp}. On end-of-file, NULL is returned. + +The @code{readdir()} function may (or may not) return entries for . or .. Your +program should tolerate reading dot and dot-dot but not require them. + +The data pointed to be @code{readdir()} may be overwritten by another call to +@code{readdir()} for the same directory stream. It will not be overwritten by +a call for another directory. + +@subheading NOTES: + +If @code{ptr} is not a pointer returned by @code{malloc()}, @code{calloc()}, or +@code{realloc()} or has been deallocated with @code{free()} or +@code{realloc()}, the results are not portable and are probably disastrous. + +The routine is implemented in Cygnus newlib. + +@page +@subsection rewinddir - Resets the readdir() pointer + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <dirent.h> + +void rewinddir( + DIR *dirp +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +No value is returned. + +@subheading DESCRIPTION: + +The @code{rewinddir()} function resets the position associated with +the directory stream pointed to by @code{dirp}. It also causes the +directory stream to refer to the current state of the directory. + +@subheading NOTES: + +NONE + +If @code{dirp} is not a pointer by @code{opendir()}, the results are +undefined. + +The routine is implemented in Cygnus newlib. + +@page +@subsection scandir - Scan a directory for matching entries + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <dirent.h> + +int scandir( + const char *dir, + struct direct ***namelist, + int (*select)(const struct dirent *), + int (*compar)(const struct dirent **, const struct dirent **) +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOMEM +Insufficient memory to complete the operation. + +@end table + +@subheading DESCRIPTION: + +The @code{scandir()} function scans the directory @code{dir}, calling +@code{select()} on each directory entry. Entries for which @code{select()} +returns non-zero are stored in strings allocated via @code{malloc()}, +sorted using @code{qsort()} with the comparison function @code{compar()}, +and collected in array @code{namelist} which is allocated via @code{malloc()}. +If @code{select} is NULL, all entries are selected. + +@subheading NOTES: + +The routine is implemented in Cygnus newlib. + +@page +@subsection telldir - Return current location in directory stream + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <dirent.h> + +off_t telldir( + DIR *dir +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EBADF +Invalid directory stream descriptor @code{dir}. + +@end table + +@subheading DESCRIPTION: + +The @code{telldir()} function returns the current location associated with the +directory stream @code{dir}. + +@subheading NOTES: + +The routine is implemented in Cygnus newlib. + +@page +@subsection closedir - Ends directory read operation + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <dirent.h> + +int closedir( + DIR *dirp +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EBADF +Invalid file descriptor + +@end table + +@subheading DESCRIPTION: + +The directory stream associated with @code{dirp} is closed. +The value in @code{dirp} may not be usable after a call to +@code{closedir()}. + +@subheading NOTES: + +NONE + +The argument to @code{closedir()} must be a pointer returned by +@code{opendir()}. If it is not, the results are not portable and +most likely unpleasant. + +The routine is implemented in Cygnus newlib. + +@page +@subsection chdir - Changes the current working directory + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int chdir( + const char *path +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Search permission is denied for a directory in a file's path prefix. + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is +in effect. + +@item ENOENT +A file or directory does not exist. + +@item ENOTDIR +A component of the specified pathname was not a directory when directory +was expected. + +@end table + +@subheading DESCRIPTION: + +The @code{chdir()} function causes the directory named by @code{path} to +become the current working directory; that is, the starting point for +searches of pathnames not beginning with a slash. + +If @code{chdir()} detects an error, the current working directory is not +changed. + +@subheading NOTES: + +NONE + +@page +@subsection getcwd - Gets current working directory + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int getcwd( void ); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument + +@item ERANGE +Result is too large + +@item EACCES +Search permission is denied for a directory in a file's path prefix. + +@end table + +@subheading DESCRIPTION: + +The @code{getcwd()} function copies the absolute pathname of the current +working directory to the character array pointed to by @code{buf}. The +@code{size} argument is the number of bytes available in @code{buf} + +@subheading NOTES: + +There is no way to determine the maximum string length that @code{fetcwd()} +may need to return. Applications should tolerate getting @code{ERANGE} +and allocate a larger buffer. + +It is possible for @code{getcwd()} to return EACCES if, say, @code{login} +puts the process into a directory without read access. + +The 1988 standard uses @code{int} instead of @code{size_t} for the second +parameter. + +@page +@subsection open - Opens a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <sys/stat.h> +#include <fcntl.h> + +int open( + const char *path, + int oflag, + mode_t mode +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b + +@item EACCES +Search permission is denied for a directory in a file's path prefix. + +@item EEXIST +The named file already exists. + +@item EINTR +Function was interrupted by a signal. + +@item EISDIR +Attempt to open a directory for writing or to rename a file to be a +directory. + +@item EMFILE +Too many file descriptors are in use by this process. + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in +effect. + +@item ENFILE +Too many files are currently open in the system. + +@item ENOENT +A file or directory does not exist. + +@item ENOSPC +No space left on disk. + +@item ENOTDIR +A component of the specified pathname was not a directory when a directory +was expected. + +@item ENXIO +No such device. This error may also occur when a device is not ready, for +example, a tape drive is off-line. + +@item EROFS +Read-only file system. +@end table + +@subheading DESCRIPTION: + +The @code{open} function establishes a connection between a file and a file +descriptor. The file descriptor is a small integer that is used by I/O +functions to reference the file. The @code{path} argument points to the +pathname for the file. + +The @code{oflag} argument is the bitwise inclusive OR of the values of +symbolic constants. The programmer must specify exactly one of the following +three symbols: + +@table @b +@item O_RDONLY +Open for reading only. + +@item O_WRONLY +Open for writing only. + +@item O_RDWR +Open for reading and writing. + +@end table + +Any combination of the following symbols may also be used. + +@table @b +@item O_APPEND +Set the file offset to the end-of-file prior to each write. + +@item O_CREAT +If the file does not exist, allow it to be created. This flag indicates +that the @code{mode} argument is present in the call to @code{open}. + +@item O_EXCL +This flag may be used only if O_CREAT is also set. It causes the call +to @code{open} to fail if the file already exists. + +@item O_NOCTTY +If @code{path} identifies a terminal, this flag prevents that teminal from +becoming the controlling terminal for thi9s process. See Chapter 8 for a +description of terminal I/O. + +@item O_NONBLOCK +Do no wait for the device or file to be ready or available. After the file +is open, the @code{read} and @code{write} calls return immediately. If the +process would be delayed in the read or write opermation, -1 is returned and +@code{errno} is set to @code{EAGAIN} instead of blocking the caller. + +@item O_TRUNC +This flag should be used only on ordinary files opened for writing. It +causes the file to be tuncated to zero length.. + +@end table + +Upon successful completion, @code{open} returns a non-negative file +descriptor. + +@subheading NOTES: + +NONE + +@page +@subsection creat - Create a new file or rewrite an existing one + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <sys/stat.h> +#include <fcntl.h> + +int creat( + const char *path, + mode_t mode +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EEXIST +@code{path} already exists and O_CREAT and O_EXCL were used. + +@item EISDIR +@code{path} refers to a directory and the access requested involved +writing + +@item ETXTBSY +@code{path} refers to an executable image which is currently being +executed and write access was requested + +@item EFAULT +@code{path} points outside your accessible address space + +@item EACCES +The requested access to the file is not allowed, or one of the +directories in @code{path} did not allow search (execute) permission. + +@item ENAMETOOLONG +@code{path} was too long. + +@item ENOENT +A directory component in @code{path} does not exist or is a dangling +symbolic link. + +@item ENOTDIR +A component used as a directory in @code{path} is not, in fact, a +directory. + +@item EMFILE +The process alreadyh has the maximum number of files open. + +@item ENFILE +The limit on the total number of files open on the system has been +reached. + +@item ENOMEM +Insufficient kernel memory was available. + +@item EROFS +@code{path} refers to a file on a read-only filesystem and write access +was requested + +@end table + +@subheading DESCRIPTION: + +@code{creat} attempts to create a file and return a file descriptor for +use in read, write, etc. + +@subheading NOTES: + +NONE + +The routine is implemented in Cygnus newlib. + +@page +@subsection umask - Sets a file creation mask. + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <sys/stat.h> + +mode_t umask( + mode_t cmask +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@subheading DESCRIPTION: + +The @code{umask()} function sets the process file creation mask to @code{cmask}. +The file creation mask is used during @code{open()}, @code{creat()}, @code{mkdir()}, +@code{mkfifo()} calls to turn off permission bits in the @code{mode} argument. +Bit positions that are set in @code{cmask} are cleared in the mode of the +created file. + +@subheading NOTES: + +NONE + +The @code{cmask} argument should have only permission bits set. All other +bits should be zero. + +In a system which supports multiple processes, the file creation mask is inherited +across @code{fork()} and @code{exec()} calls. This makes it possible to alter the +default permission bits of created files. RTEMS does not support multiple processes +so this behavior is not possible. + +@page +@subsection link - Creates a link to a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int link( + const char *existing, + const char *new +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b + +@item EACCES +Search permission is denied for a directory in a file's path prefix + +@item EEXIST +The named file already exists. + +@item EMLINK +The number of links would exceed @code{LINK_MAX}. + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in +effect. + +@item ENOENT +A file or directory does not exist. +@item ENOSPC +No space left on disk. + +@item ENOTDIR +A component of the specified pathname was not a directory when a directory +was expected. + +@item EPERM +Operation is not permitted. Process does not have the appropriate priviledges +or permissions to perform the requested operations. + +@item EROFS +Read-only file system. + +@item EXDEV +Attempt to link a file to another file system. + +@end table + +@subheading DESCRIPTION: + +The @code{link()} function atomically creates a new link for an existing file +and increments the link count for the file. + +If the @code{link()} function fails, no directories are modified. + +The @code{existing} argument should not be a directory. + +The caller may (or may not) need permission to access the existing file. + +@subheading NOTES: + +NONE + +@page +@subsection symlink - Creates a symbolic link to a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int symlink( + const char *topath, + const char *frompath +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b + +@item EACCES +Search permission is denied for a directory in a file's path prefix + +@item EEXIST +The named file already exists. + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in +effect. + +@item ENOENT +A file or directory does not exist. + +@item ENOSPC +No space left on disk. + +@item ENOTDIR +A component of the specified pathname was not a directory when a directory +was expected. + +@item EPERM +Operation is not permitted. Process does not have the appropriate priviledges +or permissions to perform the requested operations. + +@item EROFS +Read-only file system. + +@end table + +@subheading DESCRIPTION: + +The @code{symlink()} function creates a symbolic link from the frombath to the +topath. The symbolic link will be interpreted at run-time. + +If the @code{symlink()} function fails, no directories are modified. + +The caller may (or may not) need permission to access the existing file. + +@subheading NOTES: + +NONE + +@page +@subsection readlink - Obtain the name of a symbolic link destination + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int readlink( + const char *path, + char *buf, + size_t bufsize +); + +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b + +@item EACCES +Search permission is denied for a directory in a file's path prefix + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in +effect. + +@item ENOENT +A file or directory does not exist. + +@item ENOTDIR +A component of the prefix pathname was not a directory when a directory +was expected. + +@item ELOOP +Too many symbolic links were encountered in the pathname. + +@item EINVAL +The pathname does not refer to a symbolic link + +@item EFAULT +An invalid pointer was passed into the @code{readlink()} routine. + +@end table + +@subheading DESCRIPTION: + +The @code{readlink()} function places the symbolic link destination into +@code{buf} argument and returns the number of characters copied. + +If the symbolic link destination is longer than bufsize characters the +name will be truncated. + +@subheading NOTES: + +NONE + +@page +@subsection mkdir - Makes a directory + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <sys/stat.h> + +int mkdir( + const char *path, + mode_t mode +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Search permission is denied for a directory in a file's path prefix + +@item EEXIST +The name file already exist. + +@item EMLINK +The number of links would exceed LINK_MAX + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in +effect. + +@item ENOENT +A file or directory does not exist. + +@item ENOSPC +No space left on disk. + +@item ENOTDIR +A component of the specified pathname was not a directory when a directory +was expected. + +@item EROFS +Read-only file system. + +@end table + +@subheading DESCRIPTION: + +The @code{mkdir()} function creates a new diectory named @code{path}. The +permission bits (modified by the file creation mask) are set from @code{mode}. +The owner and group IDs for the directory are set from the effective user ID +and group ID. + +The new directory may (or may not) contain entries for.. and .. but is otherwise +empty. + +@subheading NOTES: + +NONE + +@page +@subsection mkfifo - Makes a FIFO special file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <sys/stat.h> + + +int mkfifo( + const char *path, + mode_t mode +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Search permission is denied for a directory in a file's path prefix + +@item EEXIST +The named file already exists. + +@item ENOENT +A file or directory does not exist. + +@item ENOSPC +No space left on disk. + +@item ENOTDIR +A component of the specified @code{path} was not a directory when a directory +was expected. + +@item EROFS +Read-only file system. + +@end table + +@subheading DESCRIPTION: + +The @code{mkfifo()} function creates a new FIFO special file named @code{path}. +The permission bits (modified by the file creation mask) are set from +@code{mode}. The owner and group IDs for the FIFO are set from the efective +user ID and group ID. + +@subheading NOTES: + +NONE + +@page +@subsection unlink - Removes a directory entry + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int unlink( + const char path +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Search permission is denied for a directory in a file's path prefix + +@item EBUSY +The directory is in use. + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in +effect. + +@item ENOENT +A file or directory does not exist. + +@item ENOTDIR +A component of the specified @code{path} was not a directory when a directory +was expected. + +@item EPERM +Operation is not permitted. Process does not have the appropriate priviledges +or permissions to perform the requested operations. + +@item EROFS +Read-only file system. + +@end table + +@subheading DESCRIPTION: + +The @code{unlink} function removes the link named by @code{path} and decrements the +link count of the file referenced by the link. When the link count goes to zero +and no process has the file open, the space occupied by the file is freed and the +file is no longer accessible. + +@subheading NOTES: + +NONE + +@page +@subsection rmdir - Delete a directory + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int rmdir( + const char *pathname +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EPERM +The filesystem containing @code{pathname} does not support the removal +of directories. + +@item EFAULT +@code{pathname} points ouside your accessible address space. + +@item EACCES +Write access to the directory containing @code{pathname} was not +allowed for the process's effective uid, or one of the directories in +@code{pathname} did not allow search (execute) permission. + +@item EPERM +The directory containing @code{pathname} has the stickybit (S_ISVTX) +set and the process's effective uid is neither the uid of the file to +be delected nor that of the director containing it. + +@item ENAMETOOLONG +@code{pathname} was too long. + +@item ENOENT +A dirctory component in @code{pathname} does not exist or is a +dangling symbolic link. + +@item ENOTDIR +@code{pathname}, or a component used as a directory in @code{pathname}, +is not, in fact, a directory. + +@item ENOTEMPTY +@code{pathname} contains entries other than . and .. . + +@item EBUSY +@code{pathname} is the current working directory or root directory of +some process + +@item EBUSY +@code{pathname} is the current directory or root directory of some +process. + +@item ENOMEM +Insufficient kernel memory was available + +@item EROGS +@code{pathname} refers to a file on a read-only filesystem. + +@item ELOOP +@code{pathname} contains a reference to a circular symbolic link + +@end table + +@subheading DESCRIPTION: + +@code{rmdir} deletes a directory, which must be empty + + +@subheading NOTES: + +NONE + +@page +@subsection rename - Renames a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int rename( + const char *old, + const char *new +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Search permission is denied for a directory in a file's path prefix. + +@item EBUSY +The directory is in use. + +@item EEXIST +The named file already exists. + +@item EINVAL +Invalid argument. + +@item EISDIR +Attempt to open a directory for writing or to rename a file to be a +directory. + +@item EMLINK +The number of links would exceed LINK_MAX. + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is +in effect. + +@item ENOENT +A file or directory does no exist. + +@item ENOSPC +No space left on disk. + +@item ENOTDIR +A component of the specified pathname was not a directory when a +directory was expected. + +@item ENOTEMPTY +Attempt to delete or rename a non-empty directory. + +@item EROFS +Read-only file system + +@item EXDEV +Attempt to link a file to another file system. +@end table + +@subheading DESCRIPTION: + +The @code{rename()} function causes the file known bo @code{old} to +now be known as @code{new}. + +Ordinary files may be renamed to ordinary files, and directories may be +renamed to directories; however, files cannot be converted using +@code{rename()}. The @code{new} pathname may not contain a path prefix +of @code{old}. + +@subheading NOTES: + +If a file already exists by the name @code{new}, it is removed. The +@code{rename()} function is atomic. If the @code{rename()} detects an +error, no files are removed. This guarantees that the +@code{rename("x", "x")} does not remove @code{x}. + +You may not rename dot or dot-dot. + +The routine is implemented in Cygnus newlib using @code{link()} and +@code{unlink()}. + +@page +@subsection stat - Gets information about a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <sys/stat.h> + +int stat( + const char *path, + struct stat *buf +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Search permission is denied for a directory in a file's path prefix. + +@item EBADF +Invalid file descriptor. + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is +in effect. + +@item ENOENT +A file or directory does not exist. + +@item ENOTDIR +A component of the specified pathname was not a directory when a +directory was expected. + +@end table + +@subheading DESCRIPTION: + +The @code{path} argument points to a pathname for a file. Read, write, or +execute permission for the file is not required, but all directories listed +in @code{path} must be searchable. The @code{stat()} function obtains +information about the named file and writes it to the area pointed to by +@code{buf}. + +@subheading NOTES: + +NONE + +@page +@subsection fstat - Gets file status + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <sys/stat.h> + +int fstat( + int fildes, + struct stat *buf +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EBADF +Invalid file descriptor + +@end table + +@subheading DESCRIPTION: + +The @code{fstat()} function obtains information about the file +associated with @code{fildes} and writes it to the area pointed +to by the @code{buf} argument. + +@subheading NOTES: + +NONE + +@page +@subsection access - Check user's permissions for a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int access( + const char *pathname, + int mode +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +The requested access would be denied, either to the file itself or +one of the directories in @code{pathname}. + +@item EFAULT +@code{pathname} points outside your accessible address space. + +@item EINVAL +@code{Mode} was incorrectly specified. + +@item ENAMETOOLONG +@code{pathname} is too long. + +@item ENOENT +A directory component in @code{pathname} would have been accessible but +does not exist or was a dangling symbolic link. + +@item ENOTDIR +A component used as a directory in @code{pathname} is not, in fact, +a directory. + +@item ENOMEM +Insufficient kernel memory was available. + +@end table + +@subheading DESCRIPTION: + +@code{Access} checks whether the process would be allowed to read, write or +test for existence of the file (or other file system object) whose name is +@code{pathname}. If @code{pathname} is a symbolic link permissions of the +file referred by this symbolic link are tested. + +@code{Mode} is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. + +@subheading NOTES: + +NONE + +@page +@subsection chmod - Changes file mode. + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <sys/stat.h> + +int chmod( + const char *path, + mode_t mode +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Search permission is denied for a directory in a file's path prefix + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in +effect. + +@item ENOENT +A file or directory does not exist. + +@item ENOTDIR +A component of the specified pathname was not a directory when a directory +was expected. + +@item EPERM +Operation is not permitted. Process does not have the appropriate priviledges +or permissions to perform the requested operations. + +@item EROFS +Read-only file system. + +@end table + +@subheading DESCRIPTION: + +Set the file permission bits, the set user ID bit, and the set group ID bit +for the file named by @code{path} to @code{mode}. If the effective user ID +does not match the owner of the file and the calling process does not have +the appropriate privileges, @code{chmod()} returns -1 and sets @code{errno} to +@code{EPERM}. + +@subheading NOTES: + +NONE + +@page +@subsection fchmod - Changes permissions of a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <sys/stat.h> + +int fchmod( + int fildes, + mode_t mode +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Search permission is denied for a directory in a file's path prefix. + +@item EBADF +The descriptor is not valid. + +@item EFAULT +@code{path} points outside your accessible address space. + +@item EIO +A low-level I/o error occurred while modifying the inode. + +@item ELOOP +@code{path} contains a circular reference + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is +in effect. + +@item ENOENT +A file or directory does no exist. + +@item ENOMEM +Insufficient kernel memory was avaliable. + +@item ENOTDIR +A component of the specified pathname was not a directory when a +directory was expected. + +@item EPERM +The effective UID does not match the owner of the file, and is not +zero + +@item EROFS +Read-only file system +@end table + +@subheading DESCRIPTION: + +The mode of the file given by @code{path} or referenced by +@code{filedes} is changed. + +@subheading NOTES: + +NONE + +@page +@subsection getdents - Get directory entries + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> +#include <linux/dirent.h> +#include <linux/unistd.h> + +long getdents( + int dd_fd, + char *dd_buf, + int dd_len +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +A successful call to @code{getdents} returns th the number of bytes read. +On end of directory, 0 is returned. When an error occurs, -1 is returned, +and @code{errno} is set appropriately. + +@table @b +@item EBADF +Invalid file descriptor @code{fd}. + +@item EFAULT +Argument points outside the calling process's address space. + +@item EINVAL +Result buffer is too small. + +@item ENOENT +No such directory. + +@item ENOTDIR +File descriptor does not refer to a directory. + +@end table + +@subheading DESCRIPTION: + +@code{getdents} reads several @code{dirent} structures from the directory +pointed by @code{fd} into the memory area pointed to by @code{dirp}. The +parameter @code{count} is the size of the memory area. + +@subheading NOTES: + +NONE + +@page +@subsection chown - Changes the owner and/or group of a file. + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <unistd.h> + +int chown( + const char *path, + uid_t owner, + gid_t group +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Search permission is denied for a directory in a file's path prefix + +@item EINVAL +Invalid argument + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in +effect. + +@item ENOENT +A file or directory does not exist. + +@item ENOTDIR +A component of the specified pathname was not a directory when a directory +was expected. + +@item EPERM +Operation is not permitted. Process does not have the appropriate priviledges +or permissions to perform the requested operations. + +@item EROFS +Read-only file system. + +@end table + +@subheading DESCRIPTION: + +The user ID and group ID of the file named by @code{path} are set to +@code{owner} and @code{path}, respectively. + +For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID) +bits are cleared. + +Some systems consider it a security violation to allow the owner of a file to +be changed, If users are billed for disk space usage, loaning a file to +another user could result in incorrect billing. The @code{chown()} function +may be restricted to privileged users for some or all files. The group ID can +still be changed to one of the supplementary group IDs. + +@subheading NOTES: + +This function may be restricted for some file. The @code{pathconf} function +can be used to test the @code{_PC_CHOWN_RESTRICTED} flag. + + + +@page +@subsection utime - Change access and/or modification times of an inode + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> + +int utime( + const char *filename, + struct utimbuf *buf +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCES +Permission to write the file is denied + +@item ENOENT +@code{Filename} does not exist + +@end table + +@subheading DESCRIPTION: + +@code{Utime} changes the access and modification times of the inode +specified by @code{filename} to the @code{actime} and @code{modtime} +fields of @code{buf} respectively. If @code{buf} is NULL, then the +access and modification times of the file are set to the current time. + +@subheading NOTES: + +NONE + +@page +@subsection ftruncate - truncate a file to a specified length + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int ftrunctate( + int fd, + size_t length +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOTDIR +A component of the path prefix is not a directory. + +@item EINVAL +The pathname contains a character with the high-order bit set. + +@item ENAMETOOLONG +A component of a pathname exceeded 255 characters, or an entire +path name exceeded 1023 characters. + +@item ENOENT +The named file does not exist. + +@item EACCES +The named file is not writable by the user. + +@item EACCES +Search permission is denied for a component of the path prefix. + +@item ELOOP +Too many symbolic links were encountered in translating the +pathname + +@item EISDIR +The named file is a directory. + +@item EROFS +The named file resides on a read-only file system + +@item ETXTBSY +The file is a pure procedure (shared text) file that is being +executed + +@item EIO +An I/O error occurred updating the inode. + +@item EFAULT +@code{Path} points outside the process's allocated address space. + +@item EBADF +The @code{fd} is not a valid descriptor. + +@end table + +@subheading DESCRIPTION: + +@code{truncate()} causes the file named by @code{path} or referenced by +@code{fd} to be truncated to at most @code{length} bytes in size. If the +file previously was larger than this size, the extra data is lost. With +@code{ftruncate()}, the file must be open for writing. + +@subheading NOTES: + +NONE + +@page +@subsection truncate - truncate a file to a specified length + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int trunctate( + const char *path, + size_t length +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOTDIR +A component of the path prefix is not a directory. + +@item EINVAL +The pathname contains a character with the high-order bit set. + +@item ENAMETOOLONG +A component of a pathname exceeded 255 characters, or an entire +path name exceeded 1023 characters. + +@item ENOENT +The named file does not exist. + +@item EACCES +The named file is not writable by the user. + +@item EACCES +Search permission is denied for a component of the path prefix. + +@item ELOOP +Too many symbolic links were encountered in translating the +pathname + +@item EISDIR +The named file is a directory. + +@item EROFS +The named file resides on a read-only file system + +@item ETXTBSY +The file is a pure procedure (shared text) file that is being +executed + +@item EIO +An I/O error occurred updating the inode. + +@item EFAULT +@code{Path} points outside the process's allocated address space. + +@item EBADF +The @code{fd} is not a valid descriptor. + +@end table + +@subheading DESCRIPTION: + +@code{truncate()} causes the file named by @code{path} or referenced by +@code{fd} to be truncated to at most @code{length} bytes in size. If the +file previously was larger than this size, the extra data is lost. With +@code{ftruncate()}, the file must be open for writing. + +@subheading NOTES: + +NONE + +@page +@subsection pathconf - Gets configuration values for files + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int pathconf( + const char *path, + int name +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument + +@item EACCES +Permission to write the file is denied + +@item ENAMETOOLONG +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC +is in effect. + +@item ENOENT +A file or directory does not exist + +@item ENOTDIR +A component of the specified @code{path} was not a directory whan a +directory was expected. + +@end table + +@subheading DESCRIPTION: + +@code{pathconf()} gets a value for the configuration option @code{name} +for the open file descriptor @code{filedes}. + +The possible values for @code{name} are: + +@table @b +@item _PC_LINK_MAX +returns the maximum number of links to the file. If @code{filedes} or +@code{path} refer to a directory, then the value applies to the whole +directory. The corresponding macro is @code{_POSIX_LINK_MAX}. + +@item _PC_MAX_CANON +returns the maximum length of a formatted input line, where @code{filedes} +or @code{path} must refer to a terminal. The corresponding macro is +@code{_POSIX_MAX_CANON}. + +@item _PC_MAX_INPUT +returns the maximum length of an input line, where @code{filedes} or +@code{path} must refer to a terminal. The corresponding macro is +@code{_POSIX_MAX_INPUT}. + +@item _PC_NAME_MAX +returns the maximum length of a filename in the directory @code{path} or +@code{filedes}. The process is allowed to create. The corresponding macro +is @code{_POSIX_NAME_MAX}. + +@item _PC_PATH_MAX +returns the maximum length of a relative pathname when @code{path} or +@code{filedes} is the current working directory. The corresponding macro +is @code{_POSIX_PATH_MAX}. + +@item _PC_PIPE_BUF +returns the size of the pipe buffer, where @code{filedes} must refer to a +pipe or FIFO and @code{path} must refer to a FIFO. The corresponding macro +is @code{_POSIX_PIPE_BUF}. + +@item _PC_CHOWN_RESTRICTED +returns nonzero if the chown(2) call may not be used on this file. If +@code{filedes} or @code{path} refer to a directory, then this applies to all +files in that directory. The corresponding macro is +@code{_POSIX_CHOWN_RESTRICTED}. + +@end table + +@subheading NOTES: + +Files with name lengths longer than the value returned for @code{name} equal +@code{_PC_NAME_MAX} may exist in the given directory. + +@page +@subsection fpathconf - Gets configuration values for files + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int fpathconf( + int filedes, + int name +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EINVAL +Invalid argument + +@item EACCES +Permission to write the file is denied +@item ENAMETOOLONG + +Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC +is in effect. + +@item ENOENT +A file or directory does not exist + +@item ENOTDIR +A component of the specified @code{path} was not a directory whan a +directory was expected. + +@end table + + +@subheading DESCRIPTION: + +@code{pathconf()} gets a value for the configuration option @code{name} +for the open file descriptor @code{filedes}. + +The possible values for name are: + +@table @b +@item _PC_LINK_MAX +returns the maximum number of links to the file. If @code{filedes} or +@code{path} refer to a directory, then the value applies to the whole +directory. The corresponding macro is _POSIX_LINK_MAX. + +@item _PC_MAX_CANON +returns the maximum length of a formatted input line, where @code{filedes} +or @code{path} must refer to a terminal. The corresponding macro is +@code{_POSIX_MAX_CANON}. + +@item _PC_MAX_INPUT +returns the maximum length of an input line, where @code{filedes} or +@code{path} must refer to a terminal. The corresponding macro is +@code{_POSIX_MAX_INPUT}. + +@item _PC_NAME_MAX +returns the maximum length of a filename in the directory @code{path} or +@code{filedes}. The process is allowed to create. The corresponding macro +is @code{_POSIX_NAME_MAX}. + +@item _PC_PATH_MAX +returns the maximum length of a relative pathname when @code{path} or +@code{filedes} is the current working directory. The corresponding macro +is @code{_POSIX_PATH_MAX}. + +@item _PC_PIPE_BUF +returns the size of the pipe buffer, where @code{filedes} must refer to a +pipe or FIFO and @code{path} must refer to a FIFO. The corresponding macro +is @code{_POSIX_PIPE_BUF}. + +@item _PC_CHOWN_RESTRICTED +returns nonzero if the @code{chown()} call may not be used on this file. If +@code{filedes} or @code{path} refer to a directory, then this applies to all +files in that directory. The corresponding macro is +@code{_POSIX_CHOWN_RESTRICTED}. + +@end table + +@subheading NOTES: + +NONE + +@page +@subsection mknod - create a directory + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> +#include <fcntl.h> +#include <sys/types.h> +#include <sys/stat.h> + +long mknod( + const char *pathname, + mode_t mode, + dev_t dev +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@code{mknod} returns zero on success, or -1 if an error occurred (in which case, +errno is set appropriately). + +@table @b +@item ENAMETOOLONG +@code{pathname} was too long. + +@item ENOENT +A directory component in @code{pathname} does not exist or is a dangling symbolic +link. + +@item ENOTDIR +A component used in the directory @code{pathname} is not, in fact, a directory. + +@item ENOMEM +Insufficient kernel memory was available + +@item EROFS +@code{pathname} refers to a file on a read-only filesystem. + +@item ELOOP +@code{pathname} contains a reference to a circular symbolic link, ie a symbolic +link whose expansion contains a reference to itself. + +@item ENOSPC +The device containing @code{pathname} has no room for the new node. + +@end table + +@subheading DESCRIPTION: + +@code{mknod} attempts to create a filesystem node (file, device special file or +named pipe) named @code{pathname}, specified by @code{mode} and @code{dev}. + +@code{mode} specifies both the permissions to use and the type of node to be created. + +It should be a combination (using bitwise OR) of one of the file types listed +below and the permissions for the new node. + +The permissions are modified by the process's @code{umask} in the usual way: the +permissions of the created node are @code{(mode & ~umask)}. + +The file type should be one of @code{S_IFREG}, @code{S_IFCHR}, @code{S_IFBLK} and +@code{S_IFIFO} to specify a normal file (which will be created empty), character +special file, block special file or FIFO (named pipe), respectively, or zero, which +will create a normal file. + +If the file type is @code{S_IFCHR} or @code{S_IFBLK} then @code{dev} specifies the major +and minor numbers of the newly created device special file; otherwise it is ignored. + +The newly created node will be owned by the effective uid of the process. If the +directory containing the node has the set group id bit set, or if the filesystem +is mounted with BSD group semantics, the new node will inherit the group ownership +from its parent directory; otherwise it will be owned by the effective gid of the +process. + + +@subheading NOTES: + +NONE diff --git a/doc/posix_users/io.t b/doc/posix_users/io.t new file mode 100644 index 0000000000..17ff64e772 --- /dev/null +++ b/doc/posix_users/io.t @@ -0,0 +1,1085 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Input and Output Primitives Manager + +@section Introduction + +The input and output primitives manager is ... + +The directives provided by the input and output primitives manager are: + +@itemize @bullet +@item @code{pipe} - YYY +@item @code{dup} - Duplicates an open file descriptor +@item @code{dup2} - Duplicates an open file descriptor +@item @code{close} - Closes a file +@item @code{read} - Reads from a file +@item @code{write} - Writes to a file +@item @code{fcntl} - Manipulates an open file descriptor +@item @code{lseek} - Reposition read/write file offset +@item @code{fsync} - Synchronize a file's complete in-core state with that on disk +@item @code{fdatasync} - synchronize a file's in-core data with that on disk +@item @code{mount} - Mount a file system +@item @code{umount} - Unmount file systems +@item @code{aio_read} - YYY +@item @code{aio_write} - YYY +@item @code{lio_listio} - YYY +@item @code{aio_error} - YYY +@item @code{aio_return} - YYY +@item @code{aio_cancel} - YYY +@item @code{aio_suspend} - YYY +@item @code{aio_fsync} - YYY +@end itemize + +@section Background + +There is currently no text in this section. + +@section Operations + +There is currently no text in this section. + +@section Directives + +This section details the input and output primitives manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection pipe - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int pipe( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection dup - Duplicates an open file descriptor + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int dup( + int fildes +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EBADF +Invalid file descriptor. + +@item EINTR +Function was interrupted by a signal. + +@item EMFILE +The process already has the maximum number of file descriptors open +and tried to open a new one. +@end table + +@subheading DESCRIPTION: + +The @code{dup} function returns the lowest numbered available file +descriptor. This new desciptor refers to the same open file as the +original descriptor and shares any locks. + +@subheading NOTES: + +NONE + +@page +@subsection dup2 - Duplicates an open file descriptor + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int dup2( + int fildes, + int fildes2 +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EBADF +Invalid file descriptor. + +@item EINTR +Function was interrupted by a signal. + +@item EMFILE +The process already has the maximum number of file descriptors open +and tried to open a new one. +@end table + +@subheading DESCRIPTION: + +@code{Dup2} creates a copy of the file descriptor @code{oldfd}. + +The old and new descriptors may be used interchangeably. They share locks, file +position pointers and flags; for example, if the file position is modified by using +@code{lseek} on one of the descriptors, the position is also changed for the other. + +@subheading NOTES: + +NONE + +@page +@subsection close - Closes a file. + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int close( + int fildes +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EBADF +Invalid file descriptor + +@item EINTR +Function was interrupted by a signal. +@end table + +@subheading DESCRIPTION: + +The @code{close()} function deallocates the file descriptor named by +@code{fildes} and makes it available for reuse. All outstanding +record locks owned by this process for the file are unlocked. + +@subheading NOTES: + +A signal can interrupt the @code{close()} function. In that case, +@code{close()} returns -1 with @code{errno} set to EINTR. The file +may or may not be closed. + +@page +@subsection read - Reads from a file. + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int read( + int fildes, + void *buf, + unsigned int nbyte +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +On error, this routine returns -1 and sets @code{errno} to one of +the following: + +@table @b +@item EAGAIN +The O_NONBLOCK flag is set for a file descriptor and the process +would be delayed in the I/O operation. + +@item EBADF +Invalid file descriptor + +@item EINTR +Function was interrupted by a signal. + +@item EIO +Input or output error + +@end table + +@subheading DESCRIPTION: + +The @code{read()} function reads @code{nbyte} bytes from the file +associated with @code{fildes} into the buffer pointed to by @code{buf}. + +The @code{read()} function returns the number of bytes actually read +and placed in the buffer. This will be less than @code{nbyte} if: + +@itemize @bullet + +@item The number of bytes left in the file is less than @code{nbyte}. + +@item The @code{read()} request was interrupted by a signal. + +@item The file is a pipe or FIFO or special file with less than @code{nbytes} +immediately available for reading. + +@end itemize + +When attempting to read from any empty pipe or FIFO: + + +@itemize @bullet + +@item If no process has the pipe open for writing, zero is returned to +indicate end-of-file. + +@item If some process has the pipe open for writing and O_NONBLOCK is set, +-1 is returned and @code{errno} is set to EAGAIN. + +@item If some process has the pipe open for writing and O_NONBLOCK is clear, +@code{read()} waits for some data to be written or the pipe to be closed. + +@end itemize + + +When attempting to read from a file other than a pipe or FIFO and no data +is available. + +@itemize @bullet + +@item If O_NONBLOCK is set, -1 is returned and @code{errno} is set to EAGAIN. + +@item If O_NONBLOCK is clear, @code{read()} waits for some data to become +available. + +@item The O_NONBLOCK flag is ignored if data is available. + +@end itemize + +@subheading NOTES: + +NONE + +@page +@subsection write - Writes to a file + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <unistd.h> + +int write( + int fildes, + const void *buf, + unsigned int nbytes +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EAGAIN +The O_NONBLOCK flag is set for a file descriptor and the process +would be delayed in the I/O operation. + +@item EBADF +Invalid file descriptor + +@item EFBIG +An attempt was made to write to a file that exceeds the maximum file +size + +@item EINTR +The function was interrupted by a signal. + +@item EIO +Input or output error. + +@item ENOSPC +No space left on disk. + +@item EPIPE +Attempt to write to a pope or FIFO with no reader. + +@end table + +@subheading DESCRIPTION: + +The @code{write()} function writes @code{nbyte} from the array pointed +to by @code{buf} into the file associated with @code{fildes}. + +If @code{nybte} is zero and the file is a regular file, the @code{write()} +function returns zero and has no other effect. If @code{nbyte} is zero +and the file is a special file, te results are not portable. + +The @code{write()} function returns the number of bytes written. This +number will be less than @code{nbytes} if there is an error. It will never +be greater than @code{nbytes}. + +@subheading NOTES: + +NONE + +@page +@subsection fcntl - Manipulates an open file descriptor + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <fcntl.h> +#include <unistd.h> + +int fcntl( + int fildes, + int cmd +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EACCESS +Search permission is denied for a direcotry in a file's path +prefix. + +@item EAGAIN +The O_NONBLOCK flag is set for a file descriptor and the process +would be delayed in the I/O operation. + +@item EBADF +Invalid file descriptor + +@item EDEADLK +An @code{fcntl} with function F_SETLKW would cause a deadlock. + +@item EINTR +The functioin was interrupted by a signal. + +@item EINVAL +Invalid argument + +@item EMFILE +Too many file descriptor or in use by the process. + +@item ENOLCK +No locks available + +@end table + +@subheading DESCRIPTION: + +@code{fcntl()} performs one of various miscellaneous operations on +@code{fd}. The operation in question is determined by @code{cmd}: + +@table @b + +@item F_DUPFD +Makes @code{arg} be a copy of @code{fd}, closing @code{fd} first if necessary. + +The same functionality can be more easily achieved by using @code{dup2()}. + +The old and new descriptors may be used interchangeably. They share locks, +file position pointers and flags; for example, if the file position is +modified by using @code{lseek()} on one of the descriptors, the position is +also changed for the other. + +The two descriptors do not share the close-on-exec flag, however. The +close-on-exec flag of the copy is off, meaning that it will be closed on +exec. + +On success, the new descriptor is returned. + +@item F_GETFD +Read the close-on-exec flag. If the low-order bit is 0, the file will +remain open across exec, otherwise it will be closed. + +@item F_SETFD +Set the close-on-exec flag to the value specified by @code{arg} (only the least +significant bit is used). + +@item F_GETFL +Read the descriptor's flags (all flags (as set by open()) are returned). + +@item F_SETFL +Set the descriptor's flags to the value specified by @code{arg}. Only +@code{O_APPEND} and @code{O_NONBLOCK} may be set. + +The flags are shared between copies (made with @code{dup()} etc.) of the same +file descriptor. + +The flags and their semantics are described in @code{open()}. + +@item F_GETLK, F_SETLK and F_SETLKW +Manage discretionary file locks. The third argument @code{arg} is a pointer to a +struct flock (that may be overwritten by this call). + +@item F_GETLK +Return the flock structure that prevents us from obtaining the lock, or set the +@code{l_type} field of the lock to @code{F_UNLCK} if there is no obstruction. + +@item F_SETLK +The lock is set (when @code{l_type} is @code{F_RDLCK} or @code{F_WRLCK}) or +cleared (when it is @code{F_UNLCK}. If lock is held by someone else, this +call returns -1 and sets @code{errno} to EACCES or EAGAIN. + +@item F_SETLKW +Like @code{F_SETLK}, but instead of returning an error we wait for the lock to +be released. + +@item F_GETOWN +Get the process ID (or process group) of the owner of a socket. + +Process groups are returned as negative values. + +@item F_SETOWN +Set the process or process group that owns a socket. + +For these commands, ownership means receiving @code{SIGIO} or @code{SIGURG} +signals. + +Process groups are specified using negative values. + +@end table + +@subheading NOTES: + +The errors returned by @code{dup2} are different from those returned by +@code{F_DUPFD}. + +@page +@subsection lseek - Reposition read/write file offset + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <unistd.h> + +int lseek( + int fildes, + off_t offset, + int whence +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EBADF +@code{Fildes} is not an open file descriptor. + +@item ESPIPE +@code{Fildes} is associated with a pipe, socket or FIFO. + +@item EINVAL +@code{Whence} is not a proper value. + +@end table + +@subheading DESCRIPTION: + +The @code{lseek} function repositions the offset of the file descriptor +@code{fildes} to the argument offset according to the directive whence. +The argument @code{fildes} must be an open file descriptor. @code{Lseek} +repositions the file pointer fildes as follows: + +@itemize @bullet + +@item +If @code{whence} is SEEK_SET, the offset is set to @code{offset} bytes. + +@item +If @code{whence} is SEEK_CUR, the offset is set to its current location +plus offset bytes. + +@item +If @code{whence} is SEEK_END, the offset is set to the size of the +file plus @code{offset} bytes. + +@end itemize + +The @code{lseek} function allows the file offset to be set beyond the end +of the existing end-of-file of the file. If data is later written at this +point, subsequent reads of the data in the gap return bytes of zeros +(until data is actually written into the gap). + +Some devices are incapable of seeking. The value of the pointer associated +with such a device is undefined. + +@subheading NOTES: + +NONE + +@page +@subsection fsync - Synchronize a file's complete in-core state with that on disk + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int fsync( + int fd +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +On success, zero is returned. On error, -1 is returned, and @code{errno} +is set appropriately. + +@table @b +@item EBADF +@code{fd} is not a valid descriptor open for writing + +@item EINVAL +@code{fd} is bound to a special file which does not support support synchronization + +@item EROFS +@code{fd} is bound to a special file which does not support support synchronization + +@item EIO +An error occurred during synchronization + +@end table + +@subheading DESCRIPTION: + +@code{fsync} copies all in-core parts of a file to disk. + +@subheading NOTES: + +NONE + +@page +@subsection fdatasync - synchronize a file's in-core data with that on disk. + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int fdatasync( + int fd +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +On success, zero is returned. On error, -1 is returned, and @code{errno} is +set appropriately. + +@table @b +@item EBADF +@code{fd} is not a valid file descriptor open for writing. + +@item EINVAL +@code{fd} is bound to a special file which does not support synchronization. + +@item EIO +An error occurred during synchronization. + +@item EROFS +@code{fd} is bound to a special file which dows not support synchronization. + +@end table + +@subheading DESCRIPTION: + +@code{fdatasync} flushes all data buffers of a file to disk (before the system call +returns). It resembles @code{fsync} but is not required to update the metadata such +as access time. + +Applications that access databases or log files often write a tiny data fragment +(e.g., one line in a log file) and then call @code{fsync} immediately in order to +ensure that the written data is physically stored on the harddisk. Unfortunately, +fsync will always initiate two write operations: one for the newly written data and +another one in order to update the modification time stored in the inode. If the +modification time is not a part of the transaction concept @code{fdatasync} can be +used to avoid unnecessary inode disk write operations. + +@subheading NOTES: + +NONE + +@page +@subsection mount - Mount a file system + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/mount.h> +#include <linux/fs.h> + +int mount( + const char *specialfile, + const char * dir, + const char * filesystemtype, + unsigned long rwflag, + const void * data +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EPERM +The user is not the super-user. + +@item ENODEV +@code{filesystemtype} not configured in the kernel. + +@item ENOTBLK +@code{specialfile} is not a block device (if a device was required). + +@item EBUSY +@code{specialfile} is already mounted. Or, it cannot be remounted +read-only, because it still holds files open for writing. Or, it +cannot be mounted on @code{dir} because @code{dir} is still busy +(it is the working directory of some task, the mount point of another +device, has open files, etc.). + +@item EINVAL +@code{specialfile} had an invalid superblock. Or, a remount was +attempted, while @code{specialfile} was not already mounted on @code{dir}. +Or, an umount was attempted, while @code{dir} was not a mount point. + +@item EFAULT +One of the pointer arguments points outside the user address space. + +@item ENOMEM +The kernel could not allocate a free page to copy filenames or data into. + +@item ENAMETOOLONG +A pathname was longer than MAXPATHLEN. + +@item ENOTDIR +A pathname was empty or had a nonexistent component. + +@item EACCES +A component of a path was not searchable. Or, mounting a read-only +filesystem was attempted without giving the MS_RDONLY flag. Or, the +block device @code{specialfile} is located on a filesystem mounted with +the MS_NODEV option. + +@item ENXIO +The major number of the block device @code{specialfile} is out of +range. + +@item EMFILE +(In case no block device is required:) Table of dummy devices is full. + +@end table + +@subheading DESCRIPTION: + +@code{Mount} attaches the filesystem specified by @code{specialfile} +(which is often a device name) to the directory specified by @code{dir}. + +Only the super-user may mount filesystems. + +The @code{filesystemtype} argument may take one of the values listed in +/proc/filesystems (link "minix", "ext2", "msdos", "proc", "nfs", +"iso9660" etc.). + +The @code{rwflag} argument has the magic number 0xCOED in the top 16 bits, +and various mount flags in the low order 16 bits. If the magic number is +absent, then the last two arguments are not used. + +The @code{data} argument is interpreted by the different file systems. + +@subheading NOTES: + +NONE + +@page +@subsection umount - Umount file systems + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/mount.h> +#include <linux/fs.h> + +int umount( + const char *specialfile +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item EPERM +The user is not the super-user. + +@item ENODEV +@code{Filesystemtype} not configured in the kernel. + +@item ENOTBLK +@code{Specialfile} is not a block device (if a device was required). + +@item EBUSY +@code{Specialfile} is already mounted. Or, it cannot be remounted +read-only, because it still holds files open for writing. Or, it +cannot be mounted on @code{dir} because @code{dir} is still busy +(it is the working directory of some task, the mount point of another +device, has open files, etc.). + +@item EINVAL +@code{specialfile} had an invalid superblock. Or, a remount was +attempted, while @code{specialfile} was not already mounted on @code{dir}. +Or, an umount was attempted, while @code{dir} was not a mount point. + +@item EFAULT +One of the pointer arguments points outside the user address space. + +@item ENOMEM +The kernel could not allocate a free page to copy filenames or data into. + +@item ENAMETOOLONG +A pathname was longer than MAXPATHLEN. + +@item ENOTDIR +A pathname was empty or had a nonexistent component. + +@item EACCES +A component of a path was not searchable. Or, mounting a read-only +filesystem was attempted without giving the MS_RDONLY flag. Or, the +block device @code{specialfile} is located on a filesystem mounted with +the MS_NODEV option. + +@item ENXIO +The major number of the block device @code{specialfile} is out of +range. + +@item EMFILE +(In case no block device is required:) Table of dummy devices is full. + +@end table + +@subheading DESCRIPTION: + +@code{Umount} removes the attachment of the filesystem specified +by @code{specialfile} or @code{dir}. + +Only the super-user may umount filesystems. + +@subheading NOTES: + +NONE + +@page +@subsection aio_read - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int aio_read( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection aio_write - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int aio_write( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection lio_listio - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int lio_listio( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection aio_error - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int aio_error( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection aio_return - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int aio_return( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection aio_cancel - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int aio_cancel( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection aio_suspend - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int aio_suspend( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. + +@page +@subsection aio_fsync - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int aio_fsync( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +This routine is not currently supported by RTEMS but could be +in a future version. diff --git a/doc/posix_users/key.texi b/doc/posix_users/key.t index 16196b6116..58e34bb259 100644 --- a/doc/posix_users/key.texi +++ b/doc/posix_users/key.t @@ -6,22 +6,8 @@ @c $Id$ @c -@ifinfo -@node Key Manager, Key Manager Introduction, pthread_cond_timedwait, Top -@end ifinfo @chapter Key Manager -@ifinfo -@menu -* Key Manager Introduction:: -* Key Manager Background:: -* Key Manager Operations:: -* Key Manager Directives:: -@end menu -@end ifinfo - -@ifinfo -@node Key Manager Introduction, Key Manager Background, Key Manager, Key Manager -@end ifinfo + @section Introduction The key manager ... @@ -35,28 +21,15 @@ The directives provided by the key manager are: @item @code{pthread_getspecific} - @end itemize -@ifinfo -@node Key Manager Background, Key Manager Operations, Key Manager Introduction, Key Manager -@end ifinfo @section Background -@ifinfo -@node Key Manager Operations, Key Manager Directives, Key Manager Background, Key Manager -@end ifinfo +There is currently no text in this section. + @section Operations -@ifinfo -@node Key Manager Directives, pthread_key_create, Key Manager Operations, Key Manager -@end ifinfo +There is currently no text in this section. + @section Directives -@ifinfo -@menu -* pthread_key_create:: -* pthread_key_delete:: -* pthread_setspecific:: -* pthread_getspecific:: -@end menu -@end ifinfo This section details the key manager's directives. A subsection is dedicated to each of this manager's directives @@ -64,9 +37,6 @@ and describes the calling sequence, related constants, usage, and status codes. @page -@ifinfo -@node pthread_key_create, pthread_key_delete, Key Manager Directives, Key Manager Directives -@end ifinfo @subsection pthread_key_create @subheading CALLING SEQUENCE: @@ -92,9 +62,6 @@ Insufficient memory exists to create the key. @end table @page -@ifinfo -@node pthread_key_delete, pthread_setspecific, pthread_key_create, Key Manager Directives -@end ifinfo @subsection pthread_key_delete @subheading CALLING SEQUENCE: @@ -120,9 +87,6 @@ The key was invalid @subheading NOTES: @page -@ifinfo -@node pthread_setspecific, pthread_getspecific, pthread_key_delete, Key Manager Directives -@end ifinfo @subsection pthread_setspecific @subheading CALLING SEQUENCE: @@ -148,9 +112,6 @@ The specified key is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_getspecific, Clock Manager, pthread_setspecific, Key Manager Directives -@end ifinfo @subsection pthread_getspecific @subheading CALLING SEQUENCE: diff --git a/doc/posix_users/memorymgmt.t b/doc/posix_users/memorymgmt.t new file mode 100644 index 0000000000..1aeaeb56a6 --- /dev/null +++ b/doc/posix_users/memorymgmt.t @@ -0,0 +1,315 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Memory Management Manager + +@section Introduction + +The +memory management manager is ... + +The directives provided by the memory management manager are: + +@itemize @bullet +@item @code{mlockall} - +@item @code{munlockall} - +@item @code{mlock} - +@item @code{munlock} - +@item @code{mmap} - +@item @code{munmap} - +@item @code{mprotect} - +@item @code{msync} - +@item @code{shm_open} - +@item @code{shm_unlink} - +@end itemize + +@section Background + +There is currently no text in this section. + +@section Operations + +There is currently no text in this section. + +@section Directives + +This section details the memory management manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection mlockall - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mlockall( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection munlockall - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int munlockall( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection mlock - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mlock( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection munlock - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int munlock( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection mmap - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mmap( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection munmap - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int munmap( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection mprotect - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mprotect( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection msync - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int msync( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection shm_open - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int shm_open( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection shm_unlink - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int shm_unlink( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/message.t b/doc/posix_users/message.t new file mode 100644 index 0000000000..d4b85ab788 --- /dev/null +++ b/doc/posix_users/message.t @@ -0,0 +1,259 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Message Passing Manager + +@section Introduction + +The +message passing manager is ... + +The directives provided by the message passing manager are: + +@itemize @bullet +@item @code{mq_open} - +@item @code{mq_close} - +@item @code{mq_unlink} - +@item @code{mq_send} - +@item @code{mq_receive} - +@item @code{mq_notify} - +@item @code{mq_setattr} - +@item @code{mq_getattr} - +@end itemize + +@section Background + +There is currently no text in this section. + +@section Operations + +There is currently no text in this section. + +@section Directives + +This section details the message passing manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection mq_open - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mq_open( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection mq_close - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mq_close( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection mq_unlink - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mq_unlink( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection mq_send - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mq_send( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection mq_receive - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mq_receive( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection mq_notify - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mq_notify( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection mq_setattr - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mq_setattr( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection mq_getattr - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int mq_getattr( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/mutex.texi b/doc/posix_users/mutex.t index 16cbe6467f..d158e07dc9 100644 --- a/doc/posix_users/mutex.texi +++ b/doc/posix_users/mutex.t @@ -6,22 +6,8 @@ @c $Id$ @c -@ifinfo -@node Mutex Manager, Mutex Manager Introduction, alarm, Top -@end ifinfo @chapter Mutex Manager -@ifinfo -@menu -* Mutex Manager Introduction:: -* Mutex Manager Background:: -* Mutex Manager Operations:: -* Mutex Manager Directives:: -@end menu -@end ifinfo - -@ifinfo -@node Mutex Manager Introduction, Mutex Manager Background, Mutex Manager, Mutex Manager -@end ifinfo + @section Introduction The mutex manager ... @@ -47,40 +33,15 @@ The directives provided by the mutex manager are: @item @code{pthread_mutex_getprioceiling} - @end itemize -@ifinfo -@node Mutex Manager Background, Mutex Manager Operations, Mutex Manager Introduction, Mutex Manager -@end ifinfo @section Background -@ifinfo -@node Mutex Manager Operations, Mutex Manager Directives, Mutex Manager Background, Mutex Manager -@end ifinfo +There is currently no text in this section. + @section Operations -@ifinfo -@node Mutex Manager Directives, pthread_mutexattr_init, Mutex Manager Operations, Mutex Manager -@end ifinfo +There is currently no text in this section. + @section Directives -@ifinfo -@menu -* pthread_mutexattr_init:: -* pthread_mutexattr_destroy:: -* pthread_mutexattr_setprotocol:: -* pthread_mutexattr_getprotocol:: -* pthread_mutexattr_setprioceiling:: -* pthread_mutexattr_getprioceiling:: -* pthread_mutexattr_setpshared:: -* pthread_mutexattr_getpshared:: -* pthread_mutex_init:: -* pthread_mutex_destroy:: -* pthread_mutex_lock:: -* pthread_mutex_trylock:: -* pthread_mutex_timedlock:: -* pthread_mutex_unlock:: -* pthread_mutex_setprioceiling:: -* pthread_mutex_getprioceiling:: -@end menu -@end ifinfo This section details the mutex manager's directives. A subsection is dedicated to each of this manager's directives @@ -88,9 +49,6 @@ and describes the calling sequence, related constants, usage, and status codes. @page -@ifinfo -@node pthread_mutexattr_init, pthread_mutexattr_destroy, Mutex Manager Directives, Mutex Manager Directives -@end ifinfo @subsection pthread_mutexattr_init @subheading CALLING SEQUENCE: @@ -116,9 +74,6 @@ The attribute pointer argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_mutexattr_destroy, pthread_mutexattr_setprotocol, pthread_mutexattr_init, Mutex Manager Directives -@end ifinfo @subsection pthread_mutexattr_destroy @subheading CALLING SEQUENCE: @@ -147,9 +102,6 @@ The attribute set is not initialized. @subheading NOTES: @page -@ifinfo -@node pthread_mutexattr_setprotocol, pthread_mutexattr_getprotocol, pthread_mutexattr_destroy, Mutex Manager Directives -@end ifinfo @subsection pthread_mutexattr_setprotocol @subheading CALLING SEQUENCE: @@ -182,9 +134,6 @@ The protocol argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_mutexattr_getprotocol, pthread_mutexattr_setprioceiling, pthread_mutexattr_setprotocol, Mutex Manager Directives -@end ifinfo @subsection pthread_mutexattr_getprotocol @subheading CALLING SEQUENCE: @@ -217,9 +166,6 @@ The protocol pointer argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_mutexattr_setprioceiling, pthread_mutexattr_getprioceiling, pthread_mutexattr_getprotocol, Mutex Manager Directives -@end ifinfo @subsection pthread_mutexattr_setprioceiling @subheading CALLING SEQUENCE: @@ -252,9 +198,6 @@ The prioceiling argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_mutexattr_getprioceiling, pthread_mutexattr_setpshared, pthread_mutexattr_setprioceiling, Mutex Manager Directives -@end ifinfo @subsection pthread_mutexattr_getprioceiling @subheading CALLING SEQUENCE: @@ -287,9 +230,6 @@ The prioceiling pointer argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_mutexattr_setpshared, pthread_mutexattr_getpshared, pthread_mutexattr_getprioceiling, Mutex Manager Directives -@end ifinfo @subsection pthread_mutexattr_setpshared @subheading CALLING SEQUENCE: @@ -322,9 +262,6 @@ The pshared argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_mutexattr_getpshared, pthread_mutex_init, pthread_mutexattr_setpshared, Mutex Manager Directives -@end ifinfo @subsection pthread_mutexattr_getpshared @subheading CALLING SEQUENCE: @@ -357,9 +294,6 @@ The pshared pointer argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_mutex_init, pthread_mutex_destroy, pthread_mutexattr_getpshared, Mutex Manager Directives -@end ifinfo @subsection pthread_mutex_init @subheading CALLING SEQUENCE: @@ -399,9 +333,6 @@ initialized, but not yet destroyed. @subheading NOTES: @page -@ifinfo -@node pthread_mutex_destroy, pthread_mutex_lock, pthread_mutex_init, Mutex Manager Directives -@end ifinfo @subsection pthread_mutex_destroy @subheading CALLING SEQUENCE: @@ -431,9 +362,6 @@ referenced by another thread. @subheading NOTES: @page -@ifinfo -@node pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_destroy, Mutex Manager Directives -@end ifinfo @subsection pthread_mutex_lock @subheading CALLING SEQUENCE: @@ -467,9 +395,6 @@ The current thread already owns the mutex. @subheading NOTES: @page -@ifinfo -@node pthread_mutex_trylock, pthread_mutex_timedlock, pthread_mutex_lock, Mutex Manager Directives -@end ifinfo @subsection pthread_mutex_trylock @subheading CALLING SEQUENCE: @@ -503,9 +428,6 @@ The current thread already owns the mutex. @subheading NOTES: @page -@ifinfo -@node pthread_mutex_timedlock, pthread_mutex_unlock, pthread_mutex_trylock, Mutex Manager Directives -@end ifinfo @subsection pthread_mutex_timedlock @subheading CALLING SEQUENCE: @@ -545,9 +467,6 @@ The current thread already owns the mutex. @page -@ifinfo -@node pthread_mutex_unlock, pthread_mutex_setprioceiling, pthread_mutex_timedlock, Mutex Manager Directives -@end ifinfo @subsection pthread_mutex_unlock @subheading CALLING SEQUENCE: @@ -573,9 +492,6 @@ The specified mutex is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_mutex_setprioceiling, pthread_mutex_getprioceiling, pthread_mutex_unlock, Mutex Manager Directives -@end ifinfo @subsection pthread_mutex_setprioceiling @subheading CALLING SEQUENCE: @@ -609,9 +525,6 @@ The specified mutex is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_mutex_getprioceiling, Condition Variable Manager, pthread_mutex_setprioceiling, Mutex Manager Directives -@end ifinfo @subsection pthread_mutex_getprioceiling @subheading CALLING SEQUENCE: diff --git a/doc/posix_users/preface.texi b/doc/posix_users/preface.texi deleted file mode 100644 index bf1653109c..0000000000 --- a/doc/posix_users/preface.texi +++ /dev/null @@ -1,24 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-1998. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@ifinfo -@node Preface, Thread Manager, Top, Top -@end ifinfo -@unnumbered Preface - -This is the user's guide for the POSIX API support for RTEMS. - -We intend for this manual to only be a listing of the API. Please -refer to the ISO/IEC 9945-1 @i{Information Technology - -Portable Operating System Interface (POSIX) - Part 1: System -Application Program Interface (API) [C Language]} for the specific -functionality and behavior of the services. - -In addition, much of the POSIX API standard is actually implemented -in the newlib ANSI C Library. Please refer to documentation on -newlib for more information on what it supplies. diff --git a/doc/posix_users/procenv.t b/doc/posix_users/procenv.t new file mode 100644 index 0000000000..9f51ba8cf4 --- /dev/null +++ b/doc/posix_users/procenv.t @@ -0,0 +1,654 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Process Environment Manager + +@section Introduction + +The +process environment manager is ... + +The directives provided by the process environment manager are: + +@itemize @bullet +@item @code{getpid} - +@item @code{getppid} - +@item @code{getuid} - +@item @code{geteuid} - +@item @code{getgid} - +@item @code{getegid} - +@item @code{setuid} - +@item @code{setgid} - +@item @code{getgroups} - +@item @code{getlogin} - +@item @code{getlogin_r} - +@item @code{getpgrp} - +@item @code{setsid} - +@item @code{setpgid} - +@item @code{uname} - +@item @code{times} - Get process times +@item @code{getenv} - +@item @code{ctermid} - +@item @code{ttyname} - +@item @code{ttyname_r} - +@item @code{isatty} - +@item @code{sysconf} - +@end itemize + +@section Background + +There is currently no text in this section. + +@section Operations + +There is currently no text in this section. + +@section Directives + +This section details the process environment manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection getpid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getpid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getppid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getppid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getuid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getuid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection geteuid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int geteuid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getgid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getgid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getegid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getegid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection setuid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int setuid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection setgid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int setgid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getgroups - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getgroups( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getlogin - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getlogin( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getlogin_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getlogin_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getpgrp - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getpgrp( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection setsid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int setsid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection setpgid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int setpgid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection uname - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int uname( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection times - Get process times + +@subheading CALLING SEQUENCE: + +@example +#include <sys/time.h> + +clock_t times( + struct tms *buf +); +@end example + +@subheading STATUS CODES: + +This routine returns the process times + +@subheading DESCRIPTION: + +@code{times} stores the current process times in @code{buf}. + +@code{struct tms} is as defined in @code{/usr/include/sys/times.h} + +@code{times} returns the number of clock ticks that have elapsed +since the systm has been up. + +@subheading NOTES: + +NONE + +@page +@subsection getenv - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getenv( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection ctermid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int ctermid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection ttyname - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int ttyname( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection ttyname_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int ttyname_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection isatty - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int isatty( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection sysconf - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sysconf( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/process.t b/doc/posix_users/process.t new file mode 100644 index 0000000000..7b5bece910 --- /dev/null +++ b/doc/posix_users/process.t @@ -0,0 +1,414 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Process Creation and Execution Manager + +@section Introduction + +The process creation and execution manager is ... + +The directives provided by the process creation and execution manager are: + +@itemize @bullet +@item @code{fork} - Create a Process +@item @code{execl} - Execute a File +@item @code{execv} - Execute a File +@item @code{execle} - Execute a File +@item @code{execve} - Execute a File +@item @code{execlp} - Execute a File +@item @code{execvp} - Execute a File +@item @code{pthread_atfork} - Register Fork Handlers +@item @code{wait} - Wait for Process Termination +@item @code{waitpid} - Wait for Process Termination +@item @code{_exit} - Terminate a Process +@end itemize + +@section Background + +There is currently no text in this section. + +@section Operations + +There is currently no text in this section. + +@section Directives + +This section details the process creation and execution manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection fork - Create a Process + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> + +int fork( void ); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOSYS +This routine is not supported by RTEMS. + +@end table + +@subheading DESCRIPTION: + +This routine is not supported by RTEMS. + +@subheading NOTES: + +NONE + +@page +@subsection execl - Execute a File + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int execl( + const char *path, + const char *arg, + ... +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOSYS +This routine is not supported by RTEMS. + +@end table + +@subheading DESCRIPTION: + +This routine is not supported by RTEMS. + +@subheading NOTES: + +NONE + +@page +@subsection execv - Execute a File + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int execv( + const char *path, + char const *argv[], + ... +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOSYS +This routine is not supported by RTEMS. + +@end table + +@subheading DESCRIPTION: + +This routine is not supported by RTEMS. + +@subheading NOTES: + +NONE + +@page +@subsection execle - Execute a File + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int execle( + const char *path, + const char *arg, + ... +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOSYS +This routine is not supported by RTEMS. + +@end table + +@subheading DESCRIPTION: + +This routine is not supported by RTEMS. + +@subheading NOTES: + +NONE + +@page +@subsection execve - Execute a File + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int execve( + const char *path, + char *const argv[], + char *const envp[] +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOSYS +This routine is not supported by RTEMS. + +@end table + +@subheading DESCRIPTION: + +This routine is not supported by RTEMS. + +@subheading NOTES: + +NONE + +@page +@subsection execlp - Execute a File + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int execlp( + const char *file, + const char *arg, + ... +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOSYS +This routine is not supported by RTEMS. + +@end table + +@subheading DESCRIPTION: + +This routine is not supported by RTEMS. + +@subheading NOTES: + +NONE + +@page +@subsection execvp - Execute a File + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int execvp( + const char *file, + char *const argv[] + ... +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOSYS +This routine is not supported by RTEMS. + +@end table + +@subheading DESCRIPTION: + +This routine is not supported by RTEMS. + +@subheading NOTES: + +NONE + +@page +@subsection pthread_atfork - Register Fork Handlers + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> + +int pthread_atfork( + void (*prepare)(void), + void (*parent)(void), + void (*child)(void) +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOSYS +This routine is not supported by RTEMS. + +@end table + +@subheading DESCRIPTION: + +This routine is not supported by RTEMS. + +@subheading NOTES: + +NONE + +@page +@subsection wait - Wait for Process Termination + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +#include <sys/types.h> +#include <sys/wait.h> + +int wait( + int *stat_loc +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOSYS +This routine is not supported by RTEMS. + +@end table + +@subheading DESCRIPTION: + +This routine is not supported by RTEMS. + +@subheading NOTES: + +NONE + +@page +@subsection waitpid - Wait for Process Termination + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int wait( + pid_t pid, + int *stat_loc, + int options +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item ENOSYS +This routine is not supported by RTEMS. + +@end table + +@subheading DESCRIPTION: + +This routine is not supported by RTEMS. + +@subheading NOTES: + +NONE + +@page +@subsection _exit - Terminate a Process + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +void _exit( + int status +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +NONE + +@subheading DESCRIPTION: + +The @code{_exit()} function terminates the calling process. + +@subheading NOTES: + +In RTEMS, a process is equivalent to the entire application on a single +processor. Invoking this service terminates the application. diff --git a/doc/posix_users/sched.texi b/doc/posix_users/sched.t index c37c24964d..be12a9c264 100644 --- a/doc/posix_users/sched.texi +++ b/doc/posix_users/sched.t @@ -6,22 +6,8 @@ @c $Id$ @c -@ifinfo -@node Scheduler Manager, Scheduler Manager Introduction, time, Top -@end ifinfo @chapter Scheduler Manager -@ifinfo -@menu -* Scheduler Manager Introduction:: -* Scheduler Manager Background:: -* Scheduler Manager Operations:: -* Scheduler Manager Directives:: -@end menu -@end ifinfo - -@ifinfo -@node Scheduler Manager Introduction, Scheduler Manager Background, Scheduler Manager, Scheduler Manager -@end ifinfo + @section Introduction The scheduler manager ... @@ -35,20 +21,8 @@ The directives provided by the scheduler manager are: @item @code{sched_yield} - @end itemize -@ifinfo -@node Scheduler Manager Background, Priority, Scheduler Manager Introduction, Scheduler Manager -@end ifinfo @section Background -@ifinfo -@menu -* Priority:: -* Scheduling Policies:: -@end menu -@end ifinfo - -@ifinfo -@node Priority, Scheduling Policies, Scheduler Manager Background, Scheduler Manager Background -@end ifinfo + @subsection Priority In the RTEMS implementation of the POSIX API, the priorities range from @@ -56,9 +30,6 @@ the low priority of sched_get_priority_min() to the highest priority of sched_get_priority_max(). Numerically higher values represent higher priorities. -@ifinfo -@node Scheduling Policies, Scheduler Manager Operations, Priority, Scheduler Manager Background -@end ifinfo @subsection Scheduling Policies The following scheduling policies are available: @@ -87,23 +58,11 @@ the thread resumes its initial priority and has its budget replenished. @end table -@ifinfo -@node Scheduler Manager Operations, Scheduler Manager Directives, Scheduling Policies, Scheduler Manager -@end ifinfo @section Operations -@ifinfo -@node Scheduler Manager Directives, sched_get_priority_min, Scheduler Manager Operations, Scheduler Manager -@end ifinfo +There is currently no text in this section. + @section Directives -@ifinfo -@menu -* sched_get_priority_min:: -* sched_get_priority_max:: -* sched_rr_get_interval:: -* sched_yield:: -@end menu -@end ifinfo This section details the scheduler manager's directives. A subsection is dedicated to each of this manager's directives @@ -111,9 +70,6 @@ and describes the calling sequence, related constants, usage, and status codes. @page -@ifinfo -@node sched_get_priority_min, sched_get_priority_max, Scheduler Manager Directives, Scheduler Manager Directives -@end ifinfo @subsection sched_get_priority_min @subheading CALLING SEQUENCE: @@ -141,9 +97,6 @@ The indicated policy is invalid. @subheading NOTES: @page -@ifinfo -@node sched_get_priority_max, sched_rr_get_interval, sched_get_priority_min, Scheduler Manager Directives -@end ifinfo @subsection sched_get_priority_max @subheading CALLING SEQUENCE: @@ -171,9 +124,6 @@ The indicated policy is invalid. @subheading NOTES: @page -@ifinfo -@node sched_rr_get_interval, sched_yield, sched_get_priority_max, Scheduler Manager Directives -@end ifinfo @subsection sched_rr_get_interval @subheading CALLING SEQUENCE: @@ -205,9 +155,6 @@ The specified interval pointer parameter is invalid. @subheading NOTES: @page -@ifinfo -@node sched_yield, Command and Variable Index, sched_rr_get_interval, Scheduler Manager Directives -@end ifinfo @subsection sched_yield @subheading CALLING SEQUENCE: diff --git a/doc/posix_users/semaphores.t b/doc/posix_users/semaphores.t new file mode 100644 index 0000000000..e3fa6b2cd1 --- /dev/null +++ b/doc/posix_users/semaphores.t @@ -0,0 +1,287 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter Semaphores Manager + +@section Introduction + +The +semaphore manager is ... + +The directives provided by the semaphore manager are: + +@itemize @bullet +@item @code{sem_init} - +@item @code{sem_destroy} - +@item @code{sem_open} - +@item @code{sem_close} - +@item @code{sem_unlink} - +@item @code{sem_wait} - +@item @code{sem_trywait} - +@item @code{sem_post} - +@item @code{sem_getvalue} - +@end itemize + +@section Background + +There is currently no text in this section. + +@section Operations + +There is currently no text in this section. + +@section Directives + +This section details the semaphore manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection sem_init - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sem_init( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection sem_destroy - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sem_destroy( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection sem_open - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sem_open( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection sem_close - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sem_close( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection sem_unlink - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sem_unlink( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection sem_wait - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sem_wait( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection sem_trywait - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sem_trywait( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection sem_post - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sem_post( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection sem_getvalue - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int sem_getvalue( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/signal.texi b/doc/posix_users/signal.t index 6d90b8cfff..f37708bd4a 100644 --- a/doc/posix_users/signal.texi +++ b/doc/posix_users/signal.t @@ -6,22 +6,8 @@ @c $Id$ @c -@ifinfo -@node Signal Manager, Signal Manager Introduction, pthread_getschedparam, Top -@end ifinfo @chapter Signal Manager -@ifinfo -@menu -* Signal Manager Introduction:: -* Signal Manager Background:: -* Signal Manager Operations:: -* Signal Manager Directives:: -@end menu -@end ifinfo - -@ifinfo -@node Signal Manager Introduction, Signal Manager Background, Signal Manager, Signal Manager -@end ifinfo + @section Introduction The signal manager ... @@ -29,40 +15,28 @@ The signal manager ... The directives provided by the signal manager are: @itemize @bullet -@item @code{sigaddset} - -@item @code{sigdelset} - -@item @code{sigfillset} - -@item @code{sigismember} - -@item @code{sigemptyset} - -@item @code{sigaction} - -@item @code{pthread_kill} - -@item @code{sigprocmask} - -@item @code{pthread_sigmask} - -@item @code{kill} - -@item @code{sigpending} - -@item @code{sigsuspend} - -@item @code{pause} - -@item @code{sigwait} - -@item @code{sigwaitinfo} - -@item @code{sigtimedwait} - -@item @code{sigqueue} - -@item @code{alarm} - +@item @code{sigaddset} - Add a Signal to a Signal Set +@item @code{sigdelset} - Delete a Signal from a Signal Set +@item @code{sigfillset} - Fill a Signal Set +@item @code{sigismember} - Is Signal a Member of a Signal Set +@item @code{sigemptyset} - Empty a Signal Set +@item @code{sigaction} - Examine and Change Signal Action +@item @code{pthread_kill} - Send a Signal to a Thread +@item @code{sigprocmask} - Examine and Change Process Blocked Signals +@item @code{pthread_sigmask} - Examine and Change Thread Blocked Signals +@item @code{kill} - Send a Signal to a Process +@item @code{sigpending} - Examine Pending Signals +@item @code{sigsuspend} - Wait for a Signal +@item @code{pause} - Suspend Process Execution +@item @code{sigwait} - Synchronously Accept a Signal +@item @code{sigwaitinfo} - Synchronously Accept a Signal +@item @code{sigtimedwait} - Synchronously Accept a Signal with Timeout +@item @code{sigqueue} - Queue a Signal to a Process +@item @code{alarm} - Schedule Alarm @end itemize -@ifinfo -@node Signal Manager Background, Signal Delivery, Signal Manager Introduction, Signal Manager -@end ifinfo @section Background -@ifinfo -@menu -* Signal Delivery:: -@end menu -@end ifinfo - -@ifinfo -@node Signal Delivery, Signal Manager Operations, Signal Manager Background, Signal Manager Background -@end ifinfo @subsection Signal Delivery Signals directed at a thread are delivered to the specified thread. @@ -71,14 +45,14 @@ Signals directed at a process are delivered to a thread which is selected based on the following algorithm: @enumerate -@item If the action for this signal is currently SIG_IGN, then the signal -is simply ignored. +@item If the action for this signal is currently @code{SIG_IGN}, +then the signal is simply ignored. @item If the currently executing thread has the signal unblocked, then the signal is delivered to it. @item If any threads are currently blocked waiting for this signal -(sigwait()), then the signal is delivered to the highest priority +(@code{sigwait()}), then the signal is delivered to the highest priority thread waiting for this signal. @item If any other threads are willing to accept delivery of the signal, then @@ -89,43 +63,17 @@ blocked on calls which may be interrupted, and finally to threads blocked on non-interruptible calls. @item In the event the signal still can not be delivered, then it is left -pending. The first thread to unblock the signal (sigprocmask() or -pthread_sigprocmask()) or to wait for this signal (sigwait()) will be -the recipient of the signal. +pending. The first thread to unblock the signal (@code{sigprocmask()} or +@code{pthread_sigprocmask()}) or to wait for this signal +(@code{sigwait()}) will be the recipient of the signal. @end enumerate -@ifinfo -@node Signal Manager Operations, Signal Manager Directives, Signal Delivery, Signal Manager -@end ifinfo @section Operations -@ifinfo -@node Signal Manager Directives, sigaddset, Signal Manager Operations, Signal Manager -@end ifinfo +There is currently no text in this section. + @section Directives -@ifinfo -@menu -* sigaddset:: -* sigdelset:: -* sigfillset:: -* sigismember:: -* sigemptyset:: -* sigaction:: -* pthread_kill:: -* sigprocmask:: -* pthread_sigmask:: -* kill:: -* sigpending:: -* sigsuspend:: -* pause:: -* sigwait:: -* sigwaitinfo:: -* sigtimedwait:: -* sigqueue:: -* alarm:: -@end menu -@end ifinfo This section details the signal manager's directives. A subsection is dedicated to each of this manager's directives @@ -133,10 +81,7 @@ and describes the calling sequence, related constants, usage, and status codes. @page -@ifinfo -@node sigaddset, sigdelset, Signal Manager Directives, Signal Manager Directives -@end ifinfo -@subsection sigaddset +@subsection sigaddset - Add a Signal to a Signal Set @subheading CALLING SEQUENCE: @@ -159,13 +104,14 @@ Invalid argument passed. @subheading DESCRIPTION: +This function adds the @code{signo} to the specified signal @code{set}. + @subheading NOTES: +NONE + @page -@ifinfo -@node sigdelset, sigfillset, sigaddset, Signal Manager Directives -@end ifinfo -@subsection sigdelset +@subsection sigdelset - Delete a Signal from a Signal Set @subheading CALLING SEQUENCE: @@ -188,13 +134,14 @@ Invalid argument passed. @subheading DESCRIPTION: +This function deletes the @code{signo} to the specified signal @code{set}. + @subheading NOTES: +NONE + @page -@ifinfo -@node sigfillset, sigismember, sigdelset, Signal Manager Directives -@end ifinfo -@subsection sigfillset +@subsection sigfillset - Fill a Signal Set @subheading CALLING SEQUENCE: @@ -207,7 +154,9 @@ int sigfillset( @end example @subheading STATUS CODES: + @table @b + @item EINVAL Invalid argument passed. @@ -215,13 +164,15 @@ Invalid argument passed. @subheading DESCRIPTION: +This function fills the specified signal @code{set} such that all +signals are set. + @subheading NOTES: +NONE + @page -@ifinfo -@node sigismember, sigemptyset, sigfillset, Signal Manager Directives -@end ifinfo -@subsection sigismember +@subsection sigismember - Is Signal a Member of a Signal Set @subheading CALLING SEQUENCE: @@ -235,7 +186,9 @@ int sigismember( @end example @subheading STATUS CODES: + @table @b + @item EINVAL Invalid argument passed. @@ -243,13 +196,15 @@ Invalid argument passed. @subheading DESCRIPTION: +This function returns returns 1 if @code{signo} is a member of @code{set} +and 0 otherwise. + @subheading NOTES: +NONE + @page -@ifinfo -@node sigemptyset, sigaction, sigismember, Signal Manager Directives -@end ifinfo -@subsection sigemptyset +@subsection sigemptyset - Empty a Signal Set @subheading CALLING SEQUENCE: @@ -264,6 +219,7 @@ int sigemptyset( @subheading STATUS CODES: @table @b + @item EINVAL Invalid argument passed. @@ -271,13 +227,15 @@ Invalid argument passed. @subheading DESCRIPTION: +This function fills the specified signal @code{set} such that all +signals are cleared. + @subheading NOTES: +NONE + @page -@ifinfo -@node sigaction, pthread_kill, sigemptyset, Signal Manager Directives -@end ifinfo -@subsection sigaction +@subsection sigaction - Examine and Change Signal Action @subheading CALLING SEQUENCE: @@ -304,14 +262,17 @@ Realtime Signals Extension option not supported. @subheading DESCRIPTION: +This function is used to change the action taken by a process on +receipt of the specfic signal @code{sig}. The new action is +specified by @code{act} and the previous action is returned +via @code{oact}. + @subheading NOTES: The signal number cannot be SIGKILL. + @page -@ifinfo -@node pthread_kill, sigprocmask, sigaction, Signal Manager Directives -@end ifinfo -@subsection pthread_kill +@subsection pthread_kill - Send a Signal to a Thread @subheading CALLING SEQUENCE: @@ -325,7 +286,9 @@ int pthread_kill( @end example @subheading STATUS CODES: + @table @b + @item ESRCH The thread indicated by the parameter thread is invalid. @@ -336,13 +299,14 @@ Invalid argument passed. @subheading DESCRIPTION: +This functions sends the specified signal @code{sig} to @code{thread}. + @subheading NOTES: +NONE + @page -@ifinfo -@node sigprocmask, pthread_sigmask, pthread_kill, Signal Manager Directives -@end ifinfo -@subsection sigprocmask +@subsection sigprocmask - Examine and Change Process Blocked Signals @subheading CALLING SEQUENCE: @@ -357,7 +321,9 @@ int sigprocmask( @end example @subheading STATUS CODES: + @table @b + @item EINVAL Invalid argument passed. @@ -365,14 +331,35 @@ Invalid argument passed. @subheading DESCRIPTION: +This function is used to alter the set of currently blocked signals +on a process wide basis. A blocked signal will not be received by the +process. The behavior of this function is dependent on the value of +@code{how} which may be one of the following: + +@table @code + +@item SIG_BLOCK +The set of blocked signals is set to the union of @code{set} and +those signals currently blocked. + +@item SIG_UNBLOCK +The signals specific in @code{set} are removed from the currently +blocked set. + +@item SIG_SETMASK +The set of currently blocked signals is set to @code{set}. + +@end table + +If @code{oset} is not @code{NULL}, then the set of blocked signals +prior to this call is returned in @code{oset}. + @subheading NOTES: - + +It is not an error to unblock a signal which is not blocked. @page -@ifinfo -@node pthread_sigmask, kill, sigprocmask, Signal Manager Directives -@end ifinfo -@subsection pthread_sigmask +@subsection pthread_sigmask - Examine and Change Thread Blocked Signals @subheading CALLING SEQUENCE: @@ -395,14 +382,35 @@ Invalid argument passed. @subheading DESCRIPTION: +This function is used to alter the set of currently blocked signals +for the calling thread. A blocked signal will not be received by the +process. The behavior of this function is dependent on the value of +@code{how} which may be one of the following: + +@table @code +@item SIG_BLOCK +The set of blocked signals is set to the union of @code{set} and +those signals currently blocked. + +@item SIG_UNBLOCK +The signals specific in @code{set} are removed from the currently +blocked set. + +@item SIG_SETMASK +The set of currently blocked signals is set to @code{set}. + +@end table + +If @code{oset} is not @code{NULL}, then the set of blocked signals +prior to this call is returned in @code{oset}. + @subheading NOTES: +It is not an error to unblock a signal which is not blocked. + @page -@ifinfo -@node kill, sigpending, pthread_sigmask, Signal Manager Directives -@end ifinfo -@subsection kill +@subsection kill - Send a Signal to a Process @subheading CALLING SEQUENCE: @@ -431,14 +439,14 @@ The process indicated by the parameter pid is invalid. @subheading DESCRIPTION: +This function sends the signal @code{sig} to the process @code{pid}. + @subheading NOTES: +NONE @page -@ifinfo -@node sigpending, sigsuspend, kill, Signal Manager Directives -@end ifinfo -@subsection sigpending +@subsection sigpending - Examine Pending Signals @subheading CALLING SEQUENCE: @@ -452,23 +460,28 @@ int sigpending( @subheading STATUS CODES: -On error, this routine returns -1 and sets errno to one of the following: +On error, this routine returns -1 and sets @code{errno} to one of +the following: @table @b + @item EFAULT Invalid address for set. @end table @subheading DESCRIPTION: + +This function allows the caller to examine the set of currently pending +signals. A pending signal is one which has been raised but is currently +blocked. The set of pending signals is returned in @code{set}. @subheading NOTES: +NONE + @page -@ifinfo -@node sigsuspend, pause, sigpending, Signal Manager Directives -@end ifinfo -@subsection sigsuspend +@subsection sigsuspend - Wait for a Signal @subheading CALLING SEQUENCE: @@ -481,8 +494,11 @@ int sigsuspend( @end example @subheading STATUS CODES: + +On error, this routine returns -1 and sets @code{errno} to one of +the following: + @table @b -Returns -1 and sets errno. @item EINTR Signal interrupted this function. @@ -490,14 +506,17 @@ Signal interrupted this function. @end table @subheading DESCRIPTION: + +This function temporarily replaces the signal mask for the process +with that specified by @code{sigmask} and blocks the calling thread +until the signal is raised. @subheading NOTES: +NONE + @page -@ifinfo -@node pause, sigwait, sigsuspend, Signal Manager Directives -@end ifinfo -@subsection pause +@subsection pause - Suspend Process Execution @subheading CALLING SEQUENCE: @@ -508,8 +527,11 @@ int pause( void ); @end example @subheading STATUS CODES: + +On error, this routine returns -1 and sets @code{errno} to one of +the following: + @table @b -Returns -1 and sets errno. @item EINTR Signal interrupted this function. @@ -517,14 +539,16 @@ Signal interrupted this function. @end table @subheading DESCRIPTION: + +This function causes the calling thread to be blocked until the signal +is received. @subheading NOTES: + +NONE @page -@ifinfo -@node sigwait, sigwaitinfo, pause, Signal Manager Directives -@end ifinfo -@subsection sigwait +@subsection sigwait - Synchronously Accept a Signal @subheading CALLING SEQUENCE: @@ -549,13 +573,17 @@ Signal interrupted this function. @subheading DESCRIPTION: +This function selects a pending signal based on the set specified in +@code{set}, atomically clears it from the set of pending signals, and +returns the signal number for that signal in @code{sig}. + + @subheading NOTES: +NONE + @page -@ifinfo -@node sigwaitinfo, sigtimedwait, sigwait, Signal Manager Directives -@end ifinfo -@subsection sigwaitinfo +@subsection sigwaitinfo - Synchronously Accept a Signal @subheading CALLING SEQUENCE: @@ -577,13 +605,16 @@ Signal interrupted this function. @subheading DESCRIPTION: +This function selects a pending signal based on the set specified in +@code{set}, atomically clears it from the set of pending signals, and +returns information about that signal in @code{info}. + @subheading NOTES: +NONE + @page -@ifinfo -@node sigtimedwait, sigqueue, sigwaitinfo, Signal Manager Directives -@end ifinfo -@subsection sigtimedwait +@subsection sigtimedwait - Synchronously Accept a Signal with Timeout @subheading CALLING SEQUENCE: @@ -612,16 +643,18 @@ Signal interrupted this function. @subheading DESCRIPTION: +This function selects a pending signal based on the set specified in +@code{set}, atomically clears it from the set of pending signals, and +returns information about that signal in @code{info}. The calling thread +will block up to @code{timeout} waiting for the signal to arrive. + @subheading NOTES: -If timeout is NULL, then the thread will wait forever for the specified -signal set. +If @code{timeout} is NULL, then the calling thread will wait forever for +the specified signal set. @page -@ifinfo -@node sigqueue, alarm, sigtimedwait, Signal Manager Directives -@end ifinfo -@subsection sigqueue +@subsection sigqueue - Queue a Signal to a Process @subheading CALLING SEQUENCE: @@ -658,15 +691,16 @@ The process pid does not exist. @end table @subheading DESCRIPTION: + +This function sends the signal specified by @code{signo} to the +process @code{pid} @subheading NOTES: +NONE @page -@ifinfo -@node alarm, Mutex Manager, sigqueue, Signal Manager Directives -@end ifinfo -@subsection alarm +@subsection alarm - Schedule Alarm @subheading CALLING SEQUENCE: @@ -680,12 +714,15 @@ unsigned int alarm( @subheading STATUS CODES: -If there was a previous alarm() request with time remaining, then this routine -returns the number of seconds until that outstanding alarm would have fired. -If no previous alarm() request was outstanding, then zero is returned. +This call always succeeds. @subheading DESCRIPTION: -@subheading NOTES: +If there was a previous @code{alarm()} request with time remaining, +then this routine returns the number of seconds until that outstanding +alarm would have fired. If no previous @code{alarm()} request was +outstanding, then zero is returned. +@subheading NOTES: +NONE diff --git a/doc/posix_users/systemdb.t b/doc/posix_users/systemdb.t new file mode 100644 index 0000000000..af3a54a09c --- /dev/null +++ b/doc/posix_users/systemdb.t @@ -0,0 +1,259 @@ +@c +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter System Databases Manager + +@section Introduction + +The +system databases manager is ... + +The directives provided by the system databases manager are: + +@itemize @bullet +@item @code{getgrgid} - +@item @code{getgrgid_r} - +@item @code{getgrnam} - +@item @code{getgrnam_r} - +@item @code{getpwuid} - +@item @code{getpwuid_r} - +@item @code{getpwnam} - +@item @code{getpwnam_r} - +@end itemize + +@section Background + +There is currently no text in this section. + +@section Operations + +There is currently no text in this section. + +@section Directives + +This section details the system databases manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection getgrgid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getgrgid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getgrgid_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getgrgid_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getgrnam - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getgrnam( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getgrnam_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getgrnam_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getpwuid - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getpwuid( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getpwuid_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getpwuid_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getpwnam - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getpwnam( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + +@page +@subsection getpwnam_r - + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +int getpwnam_r( +); +@end example +@end ifset + +@ifset is-Ada +@end ifset + +@subheading STATUS CODES: + +@table @b +@item E +The + +@end table + +@subheading DESCRIPTION: + +@subheading NOTES: + diff --git a/doc/posix_users/thread.texi b/doc/posix_users/thread.t index bb223a37ed..6ef29eb1bf 100644 --- a/doc/posix_users/thread.texi +++ b/doc/posix_users/thread.t @@ -6,22 +6,8 @@ @c $Id$ @c -@ifinfo -@node Thread Manager, Thread Manager Introduction, Preface, Top -@end ifinfo @chapter Thread Manager -@ifinfo -@menu -* Thread Manager Introduction:: -* Thread Manager Background:: -* Thread Manager Operations:: -* Thread Manager Directives:: -@end menu -@end ifinfo - -@ifinfo -@node Thread Manager Introduction, Thread Manager Background, Thread Manager, Thread Manager -@end ifinfo + @section Introduction The thread manager ... @@ -56,19 +42,8 @@ The directives provided by the thread manager are: @item @code{pthread_getschedparam} - @end itemize -@ifinfo -@node Thread Manager Background, Thread Attributes, Thread Manager Introduction, Thread Manager -@end ifinfo @section Background -@ifinfo -@menu -* Thread Attributes:: -@end menu -@end ifinfo - -@ifinfo -@node Thread Attributes, Thread Manager Operations, Thread Manager Background, Thread Manager Background -@end ifinfo + @subsection Thread Attributes Thread attributes are utilized only at thread creation time. @@ -107,44 +82,11 @@ All policies utilize the thread priority parameter. @end table -@ifinfo -@node Thread Manager Operations, Thread Manager Directives, Thread Attributes, Thread Manager -@end ifinfo @section Operations -@ifinfo -@node Thread Manager Directives, pthread_attr_init, Thread Manager Operations, Thread Manager -@end ifinfo +There is currently no text in this section. + @section Directives -@ifinfo -@menu -* pthread_attr_init:: -* pthread_attr_destroy:: -* pthread_attr_setdetachstate:: -* pthread_attr_getdetachstate:: -* pthread_attr_setstacksize:: -* pthread_attr_getstacksize:: -* pthread_attr_setstackaddr:: -* pthread_attr_getstackaddr:: -* pthread_attr_setscope:: -* pthread_attr_getscope:: -* pthread_attr_setinheritsched:: -* pthread_attr_getinheritsched:: -* pthread_attr_setschedpolicy:: -* pthread_attr_getschedpolicy:: -* pthread_attr_setschedparam:: -* pthread_attr_getschedparam:: -* pthread_create:: -* pthread_exit:: -* pthread_detach:: -* pthread_join:: -* pthread_self:: -* pthread_equal:: -* pthread_once:: -* pthread_setschedparam:: -* pthread_getschedparam:: -@end menu -@end ifinfo This section details the thread manager's directives. A subsection is dedicated to each of this manager's directives @@ -152,9 +94,6 @@ and describes the calling sequence, related constants, usage, and status codes. @page -@ifinfo -@node pthread_attr_init, pthread_attr_destroy, Thread Manager Directives, Thread Manager Directives -@end ifinfo @subsection pthread_attr_init @subheading CALLING SEQUENCE: @@ -181,9 +120,6 @@ The attribute pointer argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_destroy, pthread_attr_setdetachstate, pthread_attr_init, Thread Manager Directives -@end ifinfo @subsection pthread_attr_destroy @subheading CALLING SEQUENCE: @@ -212,9 +148,6 @@ The attribute set is not initialized. @subheading NOTES: @page -@ifinfo -@node pthread_attr_setdetachstate, pthread_attr_getdetachstate, pthread_attr_destroy, Thread Manager Directives -@end ifinfo @subsection pthread_attr_setdetachstate @subheading CALLING SEQUENCE: @@ -247,9 +180,6 @@ The detachstate argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_getdetachstate, pthread_attr_setstacksize, pthread_attr_setdetachstate, Thread Manager Directives -@end ifinfo @subsection pthread_attr_getdetachstate @subheading CALLING SEQUENCE: @@ -282,9 +212,6 @@ The detatchstate pointer argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_setstacksize, pthread_attr_getstacksize, pthread_attr_getdetachstate, Thread Manager Directives -@end ifinfo @subsection pthread_attr_setstacksize @subheading CALLING SEQUENCE: @@ -317,9 +244,6 @@ If the specified stacksize is below the minimum required for this CPU, then the stacksize will be set to the minimum for this CPU. @page -@ifinfo -@node pthread_attr_getstacksize, pthread_attr_setstackaddr, pthread_attr_setstacksize, Thread Manager Directives -@end ifinfo @subsection pthread_attr_getstacksize @subheading CALLING SEQUENCE: @@ -352,9 +276,6 @@ The stacksize pointer argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_setstackaddr, pthread_attr_getstackaddr, pthread_attr_getstacksize, Thread Manager Directives -@end ifinfo @subsection pthread_attr_setstackaddr @subheading CALLING SEQUENCE: @@ -384,9 +305,6 @@ The attribute set is not initialized. @subheading NOTES: @page -@ifinfo -@node pthread_attr_getstackaddr, pthread_attr_setscope, pthread_attr_setstackaddr, Thread Manager Directives -@end ifinfo @subsection pthread_attr_getstackaddr @subheading CALLING SEQUENCE: @@ -419,9 +337,6 @@ The stackaddr pointer argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_setscope, pthread_attr_getscope, pthread_attr_getstackaddr, Thread Manager Directives -@end ifinfo @subsection pthread_attr_setscope @subheading CALLING SEQUENCE: @@ -457,9 +372,6 @@ The contention scope specified (PTHREAD_SCOPE_SYSTEM) is not supported. @subheading NOTES: @page -@ifinfo -@node pthread_attr_getscope, pthread_attr_setinheritsched, pthread_attr_setscope, Thread Manager Directives -@end ifinfo @subsection pthread_attr_getscope @subheading CALLING SEQUENCE: @@ -492,9 +404,6 @@ The contentionscope pointer argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_setinheritsched, pthread_attr_getinheritsched, pthread_attr_getscope, Thread Manager Directives -@end ifinfo @subsection pthread_attr_setinheritsched @subheading CALLING SEQUENCE: @@ -527,9 +436,6 @@ The specified scheduler inheritance argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_getinheritsched, pthread_attr_setschedpolicy, pthread_attr_setinheritsched, Thread Manager Directives -@end ifinfo @subsection pthread_attr_getinheritsched @subheading CALLING SEQUENCE: @@ -561,9 +467,6 @@ The inheritsched pointer argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_setschedpolicy, pthread_attr_getschedpolicy, pthread_attr_getinheritsched, Thread Manager Directives -@end ifinfo @subsection pthread_attr_setschedpolicy @subheading CALLING SEQUENCE: @@ -595,9 +498,6 @@ The specified scheduler policy argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_getschedpolicy, pthread_attr_setschedparam, pthread_attr_setschedpolicy, Thread Manager Directives -@end ifinfo @subsection pthread_attr_getschedpolicy @subheading CALLING SEQUENCE: @@ -629,9 +529,6 @@ The specified scheduler policy argument pointer is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_setschedparam, pthread_attr_getschedparam, pthread_attr_getschedpolicy, Thread Manager Directives -@end ifinfo @subsection pthread_attr_setschedparam @subheading CALLING SEQUENCE: @@ -663,9 +560,6 @@ The specified scheduler parameter argument is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_attr_getschedparam, pthread_create, pthread_attr_setschedparam, Thread Manager Directives -@end ifinfo @subsection pthread_attr_getschedparam @subheading CALLING SEQUENCE: @@ -697,9 +591,6 @@ The specified scheduler parameter argument pointer is invalid. @subheading NOTES: @page -@ifinfo -@node pthread_create, pthread_exit, pthread_attr_getschedparam, Thread Manager Directives -@end ifinfo @subsection pthread_create @subheading CALLING SEQUENCE: @@ -761,9 +652,6 @@ Invalid argument passed. @subheading NOTES: @page -@ifinfo -@node pthread_exit, pthread_detach, pthread_create, Thread Manager Directives -@end ifinfo @subsection pthread_exit @subheading CALLING SEQUENCE: @@ -787,9 +675,6 @@ void pthread_exit( @subheading NOTES: @page -@ifinfo -@node pthread_detach, pthread_join, pthread_exit, Thread Manager Directives -@end ifinfo @subsection pthread_detach @subheading CALLING SEQUENCE: @@ -821,9 +706,6 @@ will remain joined with that thread. Any subsequent calls to pthread_join on the specified thread will fail. @page -@ifinfo -@node pthread_join, pthread_self, pthread_detach, Thread Manager Directives -@end ifinfo @subsection pthread_join @subheading CALLING SEQUENCE: @@ -861,9 +743,6 @@ on the specified thread will fail. If value_ptr is NULL, then no value is returned. @page -@ifinfo -@node pthread_self, pthread_equal, pthread_join, Thread Manager Directives -@end ifinfo @subsection pthread_self @subheading CALLING SEQUENCE: @@ -883,9 +762,6 @@ This routine returns the id of the calling thread. @subheading NOTES: @page -@ifinfo -@node pthread_equal, pthread_once, pthread_self, Thread Manager Directives -@end ifinfo @subsection pthread_equal @subheading CALLING SEQUENCE: @@ -917,9 +793,6 @@ The thread ids are equal. The behavior is undefined if the thread IDs are not valid. @page -@ifinfo -@node pthread_once, pthread_setschedparam, pthread_equal, Thread Manager Directives -@end ifinfo @subsection pthread_once @subheading CALLING SEQUENCE: @@ -944,9 +817,6 @@ NONE @subheading NOTES: @page -@ifinfo -@node pthread_setschedparam, pthread_getschedparam, pthread_once, Thread Manager Directives -@end ifinfo @subsection pthread_setschedparam @subheading CALLING SEQUENCE: @@ -988,9 +858,6 @@ The thread indicated was invalid. @subheading NOTES: @page -@ifinfo -@node pthread_getschedparam, Signal Manager, pthread_setschedparam, Thread Manager Directives -@end ifinfo @subsection pthread_getschedparam @subheading CALLING SEQUENCE: |