diff options
Diffstat (limited to '')
28 files changed, 0 insertions, 14354 deletions
diff --git a/doc/posix_users/Makefile.am b/doc/posix_users/Makefile.am deleted file mode 100644 index e8df5bac18..0000000000 --- a/doc/posix_users/Makefile.am +++ /dev/null @@ -1,139 +0,0 @@ -# -# COPYRIGHT (c) 1988-2002. -# On-Line Applications Research Corporation (OAR). -# All rights reserved. - -PROJECT = posix_users - -include $(top_srcdir)/project.am -include $(top_srcdir)/main.am - -GENERATED_FILES = cancel.texi clock.texi cond.texi cspecific.texi \ - device.texi files.texi io.texi key.texi memorymgmt.texi message.texi \ - mutex.texi procenv.texi process.texi sched.texi semaphores.texi \ - signal.texi status.texi systemdb.texi thread.texi timer.texi libc.texi \ - libm.texi - -COMMON_FILES += $(top_srcdir)/common/cpright.texi - -FILES = preface.texi -info_TEXINFOS = posix_users.texi -posix_users_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES) - -process.texi: process.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -procenv.texi: procenv.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -files.texi: files.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -thread.texi: thread.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -signal.texi: signal.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -mutex.texi: mutex.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -cond.texi: cond.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -key.texi: key.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -clock.texi: clock.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -timer.texi: timer.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -sched.texi: sched.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -io.texi: io.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -device.texi: device.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -cspecific.texi: cspecific.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -semaphores.texi: semaphores.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -memorymgmt.texi: memorymgmt.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -message.texi: message.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -cancel.texi: cancel.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -systemdb.texi: systemdb.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -status.texi: status.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -libc.texi: libc.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -libm.texi: libm.t - $(BMENU2) -p "" \ - -u "Top" \ - -n "" < $< > $@ - -noinst_SCRIPTS = gen_size_report -EXTRA_DIST = cancel.t clock.t cond.t cspecific.t device.t files.t io.t key.t \ - libc.t libm.t memorymgmt.t message.t mutex.t procenv.t process.t sched.t \ - semaphores.t signal.t status.t systemdb.t thread.t timer.t \ - gen_size_report - -CLEANFILES += posix_users.info posix_users.info-? posix_users.info-?? diff --git a/doc/posix_users/cancel.t b/doc/posix_users/cancel.t deleted file mode 100644 index 09235c2326..0000000000 --- a/doc/posix_users/cancel.t +++ /dev/null @@ -1,236 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Thread Cancellation Manager - -@section Introduction - -The -thread cancellation manager is ... - -The directives provided by the thread cancellation manager are: - -@itemize @bullet -@item @code{pthread_cancel} - Cancel Execution of a Thread -@item @code{pthread_setcancelstate} - Set Cancelability State -@item @code{pthread_setcanceltype} - Set Cancelability Type -@item @code{pthread_testcancel} - Create Cancellation Point -@item @code{pthread_cleanup_push} - Establish Cancellation Handler -@item @code{pthread_cleanup_pop} - Remove Cancellation Handler -@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 thread cancellation 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. - -@c -@c -@c -@page -@subsection pthread_cancel - Cancel Execution of a Thread - -@findex pthread_cancel -@cindex cancel execution of a thread - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int pthread_cancel( -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item E -The - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_setcancelstate - Set Cancelability State - -@findex pthread_setcancelstate -@cindex set cancelability state - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int pthread_setcancelstate( -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item E -The - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_setcanceltype - Set Cancelability Type - -@findex pthread_setcanceltype -@cindex set cancelability type - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int pthread_setcanceltype( -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item E -The - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_testcancel - Create Cancellation Point - -@findex pthread_testcancel -@cindex create cancellation point - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int pthread_testcancel( -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item E -The - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_cleanup_push - Establish Cancellation Handler - -@findex pthread_cleanup_push -@cindex establish cancellation handler - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int pthread_cleanup_push( -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item E -The - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_cleanup_pop - Remove Cancellation Handler - -@findex pthread_cleanup_pop -@cindex remove cancellation handler - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int pthread_cleanup_push( -); -@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/clock.t b/doc/posix_users/clock.t deleted file mode 100644 index 9b52c2ce04..0000000000 --- a/doc/posix_users/clock.t +++ /dev/null @@ -1,366 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Clock Manager - -@section Introduction - -The clock manager provides services two primary classes -of services. The first focuses on obtaining and setting -the current date and time. The other category of services -focus on allowing a thread to delay for a specific length -of time. - -The directives provided by the clock manager are: - -@itemize @bullet -@item @code{clock_gettime} - Obtain Time of Day -@item @code{clock_settime} - Set Time of Day -@item @code{clock_getres} - Get Clock Resolution -@item @code{sleep} - Delay Process Execution -@item @code{usleep} - Delay Process Execution in Microseconds -@item @code{nanosleep} - Delay with High Resolution -@item @code{gettimeofday} - Get the Time of Day -@item @code{time} - Get time in seconds -@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 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. - -@subsection clock_gettime - Obtain Time of Day - -@findex clock_gettime -@cindex obtain time of day - -@subheading CALLING SEQUENCE: - -@example -#include <time.h> - -int clock_gettime( - clockid_t clock_id, - struct timespec *tp -); -@end example - -@subheading STATUS CODES: - -On error, this routine returns -1 and sets errno to one of the following: - -@table @b -@item EINVAL -The tp pointer parameter is invalid. - -@item EINVAL -The clock_id specified is invalid. -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection clock_settime - Set Time of Day - -@findex clock_settime -@cindex set time of day - -@subheading CALLING SEQUENCE: - -@example -#include <time.h> - -int clock_settime( - clockid_t clock_id, - const struct timespec *tp -); -@end example - -@subheading STATUS CODES: - -On error, this routine returns -1 and sets errno to one of the following: - -@table @b -@item EINVAL -The tp pointer parameter is invalid. - -@item EINVAL -The clock_id specified is invalid. - -@item EINVAL -The contents of the tp structure are invalid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection clock_getres - Get Clock Resolution - -@findex clock_getres -@cindex get clock resolution - -@subheading CALLING SEQUENCE: - -@example -#include <time.h> - -int clock_getres( - clockid_t clock_id, - struct timespec *res -); -@end example - -@subheading STATUS CODES: - -On error, this routine returns -1 and sets errno to one of the following: - -@table @b -@item EINVAL -The res pointer parameter is invalid. - -@item EINVAL -The clock_id specified is invalid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -If res is NULL, then the resolution is not returned. - -@c -@c -@c -@page -@subsection sleep - Delay Process Execution - -@findex sleep -@cindex delay process execution - -@subheading CALLING SEQUENCE: - -@example -#include <unistd.h> - -unsigned int sleep( - unsigned int seconds -); -@end example - -@subheading STATUS CODES: - -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. - -@c -@c -@c -@page -@subsection usleep - Delay Process Execution in Microseconds - -@findex usleep -@cindex delay process execution -@cindex delay process execution -@cindex usecs delay process execution -@cindex microsecond delay process execution - -@subheading CALLING SEQUENCE: - -@example -#include <time.h> - -useconds_t usleep( - useconds_t useconds -); -@end example - -@subheading STATUS CODES: - -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}. - -The @code{usleep()} function suspends the calling thread from execution -until either the number of microseconds specified by the -@code{useconds} argument has elapsed or a signal is delivered to the -calling thread and its action is to invoke a signal-catching function -or to terminate the process. - -Because of other activity, or because of the time spent in -processing the call, the actual length of time the thread is -blocked may be longer than -the amount of time specified. - -@subheading NOTES: - -This call is interruptible by a signal. - -The Single UNIX Specification allows this service to be implemented using -the same timer as that used by the @code{alarm()} service. This is -@b{NOT} the case for @b{RTEMS} and this call has no interaction with -the @code{SIGALRM} signal. - -@c -@c -@c -@page -@subsection nanosleep - Delay with High Resolution - -@findex nanosleep -@cindex delay with high resolution - -@subheading CALLING SEQUENCE: - -@example -#include <time.h> - -int nanosleep( - const struct timespec *rqtp, - struct timespec *rmtp -); -@end example - -@subheading STATUS CODES: - -On error, this routine returns -1 and sets errno to one of the following: - -@table @b -@item EINTR -The routine was interrupted by a signal. - -@item EAGAIN -The requested sleep period specified negative seconds or nanoseconds. - -@item EINVAL -The requested sleep period specified an invalid number for the nanoseconds -field. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -This call is interruptible by a signal. - -@c -@c -@c -@page -@subsection gettimeofday - Get the Time of Day - -@findex gettimeofday -@cindex 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. - -@c -@c -@c -@page -@subsection time - Get time in seconds - -@findex time -@cindex get time in seconds - -@subheading CALLING SEQUENCE: - -@example -#include <time.h> - -int time( - time_t *tloc -); -@end example - -@subheading STATUS CODES: - -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.t b/doc/posix_users/cond.t deleted file mode 100644 index c95cc07650..0000000000 --- a/doc/posix_users/cond.t +++ /dev/null @@ -1,380 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Condition Variable Manager - -@section Introduction - -The condition variable manager ... - -The directives provided by the condition variable manager are: - -@itemize @bullet -@item @code{pthread_condattr_init} - Initialize a Condition Variable Attribute Set -@item @code{pthread_condattr_destroy} - Destroy a Condition Variable Attribute Set -@item @code{pthread_condattr_setpshared} - Set Process Shared Attribute -@item @code{pthread_condattr_getpshared} - Get Process Shared Attribute -@item @code{pthread_cond_init} - Initialize a Condition Variable -@item @code{pthread_cond_destroy} - Destroy a Condition Variable -@item @code{pthread_cond_signal} - Signal a Condition Variable -@item @code{pthread_cond_broadcast} - Broadcast a Condition Variable -@item @code{pthread_cond_wait} - Wait on a Condition Variable -@item @code{pthread_cond_timedwait} - With with Timeout a Condition Variable -@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 condition variable 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. - -@c -@c -@c -@page -@subsection pthread_condattr_init - Initialize a Condition Variable Attribute Set - -@findex pthread_condattr_init -@cindex initialize a condition variable attribute set - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_condattr_init( - pthread_condattr_t *attr -); -@end example - -@subheading STATUS CODES: -@table @b -@item ENOMEM -Insufficient memory is available to initialize the condition variable -attributes object. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_condattr_destroy - Destroy a Condition Variable Attribute Set - -@findex pthread_condattr_destroy -@cindex destroy a condition variable attribute set - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_condattr_destroy( - pthread_condattr_t *attr -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The attribute object specified is invalid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_condattr_setpshared - Set Process Shared Attribute - -@findex pthread_condattr_setpshared -@cindex set process shared attribute - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_condattr_setpshared( - pthread_condattr_t *attr, - int pshared -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -Invalid argument passed. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_condattr_getpshared - Get Process Shared Attribute - -@findex pthread_condattr_getpshared -@cindex get process shared attribute - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_condattr_getpshared( - const pthread_condattr_t *attr, - int *pshared -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -Invalid argument passed. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c -@c -@page -@subsection pthread_cond_init - Initialize a Condition Variable - -@findex pthread_cond_init -@cindex initialize a condition variable - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_cond_init( - pthread_cond_t *cond, - const pthread_condattr_t *attr -); -@end example - -@subheading STATUS CODES: -@table @b -@item EAGAIN -The system lacked a resource other than memory necessary to create the -initialize the condition variable object. - -@item ENOMEM -Insufficient memory is available to initialize the condition variable object. - -@item EBUSY -The specified condition variable has already been initialized. - -@item EINVAL -The specified attribute value is invalid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_cond_destroy - Destroy a Condition Variable - -@findex pthread_cond_destroy -@cindex destroy a condition variable - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_cond_destroy( - pthread_cond_t *cond -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The specified condition variable is invalid. - -@item EBUSY -The specified condition variable is currently in use. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_cond_signal - Signal a Condition Variable - -@findex pthread_cond_signal -@cindex signal a condition variable - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_cond_signal( - pthread_cond_t *cond -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The specified condition variable is not valid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -This routine should not be invoked from a handler from an asynchronous signal -handler or an interrupt service routine. - -@c -@c -@c -@page -@subsection pthread_cond_broadcast - Broadcast a Condition Variable - -@findex pthread_cond_broadcast -@cindex broadcast a condition variable - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_cond_broadcast( - pthread_cond_t *cond -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The specified condition variable is not valid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -This routine should not be invoked from a handler from an asynchronous signal -handler or an interrupt service routine. - -@c -@c -@c -@page -@subsection pthread_cond_wait - Wait on a Condition Variable - -@findex pthread_cond_wait -@cindex wait on a condition variable - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_cond_wait( - pthread_cond_t *cond, - pthread_mutex_t *mutex -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The specified condition variable or mutex is not initialized OR different -mutexes were specified for concurrent pthread_cond_wait() and -pthread_cond_timedwait() operations on the same condition variable OR -the mutex was not owned by the current thread at the time of the call. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_cond_timedwait - Wait with Timeout a Condition Variable - -@findex pthread_cond_timedwait -@cindex wait with timeout a condition variable - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_cond_timedwait( - pthread_cond_t *cond, - pthread_mutex_t *mutex, - const struct timespec *abstime -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The specified condition variable or mutex is not initialized OR different -mutexes were specified for concurrent pthread_cond_wait() and -pthread_cond_timedwait() operations on the same condition variable OR -the mutex was not owned by the current thread at the time of the call. - -@item ETIMEDOUT -The specified time has elapsed without the condition variable being -satisfied. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - diff --git a/doc/posix_users/cspecific.t b/doc/posix_users/cspecific.t deleted file mode 100644 index 8b82bd13cc..0000000000 --- a/doc/posix_users/cspecific.t +++ /dev/null @@ -1,746 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@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} - Set the Current Locale -@item @code{fileno} - Obtain File Descriptor Number for this File -@item @code{fdopen} - Associate Stream with File Descriptor -@item @code{flockfile} - Acquire Ownership of File Stream -@item @code{ftrylockfile} - Poll to Acquire Ownership of File Stream -@item @code{funlockfile} - Release Ownership of File Stream -@item @code{getc_unlocked} - Get Character without Locking -@item @code{getchar_unlocked} - Get Character from stdin without Locking -@item @code{putc_unlocked} - Put Character without Locking -@item @code{putchar_unlocked} - Put Character to stdin without Locking -@item @code{setjmp} - Save Context for Non-Local Goto -@item @code{longjmp} - Non-Local Jump to a Saved Context -@item @code{sigsetjmp} - Save Context with Signal Status for Non-Local Goto -@item @code{siglongjmp} - Non-Local Jump with Signal Status to a Saved Context -@item @code{tzset} - Initialize Time Conversion Information -@item @code{strtok_r} - Reentrant Extract Token from String -@item @code{asctime_r} - Reentrant struct tm to ASCII Time Conversion -@item @code{ctime_r} - Reentrant time_t to ASCII Time Conversion -@item @code{gmtime_r} - Reentrant UTC Time Conversion -@item @code{localtime_r} - Reentrant Local Time Conversion -@item @code{rand_r} - Reentrant Random Number Generation -@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. - -@c -@c -@c -@page -@subsection setlocale - Set the Current Locale - -@findex setlocale -@cindex set the current locale - -@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: - -@c -@c -@c -@page -@subsection fileno - Obtain File Descriptor Number for this File - -@findex fileno -@cindex obtain file descriptor number for this file - -@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: - -@c -@c -@c -@page -@subsection fdopen - Associate Stream with File Descriptor - -@findex fdopen -@cindex associate stream with file descriptor - -@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: - -@c -@c -@c -@page -@subsection flockfile - Acquire Ownership of File Stream - -@findex flockfile -@cindex acquire ownership of file stream - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int flockfile( -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item E -The - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection ftrylockfile - Poll to Acquire Ownership of File Stream - -@findex ftrylockfile -@cindex poll to acquire ownership of file stream - -@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: - -@c -@c -@c -@page -@subsection funlockfile - Release Ownership of File Stream - -@findex funlockfile -@cindex release ownership of file stream - -@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: - -@c -@c -@c -@page -@subsection getc_unlocked - Get Character without Locking - -@findex getc_unlocked -@cindex get character without locking - -@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: - -@c -@c -@c -@page -@subsection getchar_unlocked - Get Character from stdin without Locking - -@findex getchar_unlocked -@cindex get character from stdin without locking - -@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: - -@c -@c -@c -@page -@subsection putc_unlocked - Put Character without Locking - -@findex putc_unlocked -@cindex put character without locking - -@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: - -@c -@c -@c -@page -@subsection putchar_unlocked - Put Character to stdin without Locking - -@findex putchar_unlocked -@cindex put character to stdin without locking - -@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: - -@c -@c -@c -@page -@subsection setjmp - Save Context for Non-Local Goto - -@findex setjmp -@cindex save context for non - -@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: - -@c -@c -@c -@page -@subsection longjmp - Non-Local Jump to a Saved Context - -@findex longjmp -@cindex non - -@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: - -@c -@c -@c -@page -@subsection sigsetjmp - Save Context with Signal Status for Non-Local Goto - -@findex sigsetjmp -@cindex save context with signal status for non - -@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: - -@c -@c -@c -@page -@subsection siglongjmp - Non-Local Jump with Signal Status to a Saved Context - -@findex siglongjmp -@cindex non - -@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: - -@c -@c -@c -@page -@subsection tzset - Initialize Time Conversion Information - -@findex tzset -@cindex initialize time conversion information - -@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: - -@c -@c -@c -@page -@subsection strtok_r - Reentrant Extract Token from String - -@findex strtok_r -@cindex reentrant extract token from string - -@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: - -@c -@c -@c -@page -@subsection asctime_r - Reentrant struct tm to ASCII Time Conversion - -@findex asctime_r -@cindex reentrant struct tm to ascii time conversion - -@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: - -@c -@c -@c -@page -@subsection ctime_r - Reentrant time_t to ASCII Time Conversion - -@findex ctime_r -@cindex reentrant time_t to ascii time conversion - -@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: - -@c -@c -@c -@page -@subsection gmtime_r - Reentrant UTC Time Conversion - -@findex gmtime_r -@cindex reentrant utc time conversion - -@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: - -@c -@c -@c -@page -@subsection localtime_r - Reentrant Local Time Conversion - -@findex localtime_r -@cindex reentrant local time conversion - -@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: - -@c -@c -@c -@page -@subsection rand_r - Reentrant Random Number Generation - -@findex rand_r -@cindex reentrant random number generation - -@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 deleted file mode 100644 index 32773e57bf..0000000000 --- a/doc/posix_users/device.t +++ /dev/null @@ -1,537 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@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. - -@c -@c -@c -@page -@subsection cfgetispeed - Reads terminal input baud rate - -@findex cfgetispeed -@cindex 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. - -@c -@c -@c -@page -@subsection cfgetospeed - Reads terminal output baud rate - -@findex cfgetospeed -@cindex 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. - -@c -@c -@c -@page -@subsection cfsetispeed - Sets terminal input baud rate - -@findex cfsetispeed -@cindex 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. - -@c -@c -@c -@page -@subsection cfsetospeed - Sets terminal output baud rate - -@findex cfsetospeed -@cindex 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. - -@c -@c -@c -@page -@subsection tcgetattr - Gets terminal attributes - -@findex tcgetattr -@cindex 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 - -@c -@c -@c -@page -@subsection tcsetattr - Set terminal attributes - -@findex tcsetattr -@cindex 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: - -@c -@c -@c -@page -@subsection tcsendbreak - Sends a break to a terminal - -@findex tcsendbreak -@cindex sends a break to a terminal - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int tcsendbreak( - int fd -); -@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. - -@c -@c -@c -@page -@subsection tcdrain - Waits for all output to be transmitted to the terminal. - -@findex tcdrain -@cindex 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 - -@c -@c -@c -@page -@subsection tcflush - Discards terminal data - -@findex tcflush -@cindex discards terminal data - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int tcflush( - int fd -); -@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. - -@c -@c -@c -@page -@subsection tcflow - Suspends/restarts terminal output. - -@findex tcflow -@cindex suspends/restarts terminal output. - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int tcflow( - int fd -); -@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. - -@c -@c -@c -@page -@subsection tcgetpgrp - Gets foreground process group ID - -@findex tcgetpgrp -@cindex 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. - -@c -@c -@c -@page -@subsection tcsetpgrp - Sets foreground process group ID - -@findex tcsetpgrp -@cindex 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 deleted file mode 100644 index bc8564747a..0000000000 --- a/doc/posix_users/files.t +++ /dev/null @@ -1,2407 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@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{fchdir} - 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{lstat} - Gets file status -@item @code{access} - Check 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 - -@subsection Path Name Evaluation - -A pathname is a string that consists of no more than @code{PATH_MAX} -bytes, including the terminating null character. A pathname has an optional -beginning slash, followed by zero or more filenames separated by slashes. -If the pathname refers to a directory, it may also have one or more trailing -slashes. Multiple successive slahes are considered to be the same as -one slash. - -POSIX allows a pathname that begins with precisely two successive slashes to be -interpreted in an implementation-defined manner. RTEMS does not currently -recognize this as a special condition. Any number of successive -slashes is treated the same as a single slash. POSIX requires that -an implementation treat more than two leading slashes as a single slash. - -@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. - -@c -@c -@c -@page -@subsection opendir - Open a Directory - -@findex opendir -@cindex 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. - -@c -@c -@c -@page -@subsection readdir - Reads a directory - -@findex readdir -@cindex 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. - -@c -@c -@c -@page -@subsection rewinddir - Resets the readdir() pointer - -@findex rewinddir -@cindex 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. - -@c -@c -@c -@page -@subsection scandir - Scan a directory for matching entries - -@findex scandir -@cindex scan a directory for matching entries - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <dirent.h> - -int scandir( - const char *dir, - struct dirent ***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. - -@c -@c -@c -@page -@subsection telldir - Return current location in directory stream - -@findex telldir -@cindex 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. - -@c -@c -@c -@page -@subsection closedir - Ends directory read operation - -@findex closedir -@cindex 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. - -@c -@c -@c -@page -@subsection chdir - Changes the current working directory - -@findex chdir -@cindex 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: - -On error, this routine returns -1 and sets @code{errno} to one of -the following: - -@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 - -@c -@c -@c -@page -@subsection fchdir - Changes the current working directory - -@findex fchdir -@cindex changes the current working directory - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <unistd.h> - -int fchdir( - int fd -); -@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 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{fchdir()} function causes the directory named by @code{fd} to -become the current working directory; that is, the starting point for -searches of pathnames not beginning with a slash. - -If @code{fchdir()} detects an error, the current working directory is not -changed. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection getcwd - Gets current working directory - -@findex getcwd -@cindex 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. - -@c -@c -@c -@page -@subsection open - Opens a file - -@findex open -@cindex 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 - -@c -@c -@c -@page -@subsection creat - Create a new file or rewrite an existing one - -@findex creat -@cindex 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. - -@c -@c -@c -@page -@subsection umask - Sets a file creation mask. - -@findex umask -@cindex 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. - -@c -@c -@c -@page -@subsection link - Creates a link to a file - -@findex link -@cindex 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 - -@c -@c -@c -@page -@subsection symlink - Creates a symbolic link to a file - -@findex symlink -@cindex 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 - -@c -@c -@c -@page -@subsection readlink - Obtain the name of a symbolic link destination - -@findex readlink -@cindex 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 - -@c -@c -@c -@page -@subsection mkdir - Makes a directory - -@findex mkdir -@cindex 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 - -@c -@c -@c -@page -@subsection mkfifo - Makes a FIFO special file - -@findex mkfifo -@cindex 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 - -@c -@c -@c -@page -@subsection unlink - Removes a directory entry - -@findex unlink -@cindex 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 - -@c -@c -@c -@page -@subsection rmdir - Delete a directory - -@findex rmdir -@cindex 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 - -@c -@c -@c -@page -@subsection rename - Renames a file - -@findex rename -@cindex 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()}. - -@c -@c -@c -@page -@subsection stat - Gets information about a file - -@findex stat -@cindex 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 - -@c -@c -@c -@page -@subsection fstat - Gets file status - -@findex fstat -@cindex 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: - -If the filesystem object referred to by @code{fildes} is a -link, then the information returned in @code{buf} refers -to the destination of that link. This is in contrast to -@code{lstat()} which does not follow the link. - -@c -@c -@c -@page -@subsection lstat - Gets file status - -@findex lstat -@cindex gets file status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <sys/types.h> -#include <sys/stat.h> - -int lstat( - 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{lstat()} 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: - -If the filesystem object referred to by @code{fildes} is a -link, then the information returned in @code{buf} refers -to the link itself. This is in contrast to @code{fstat()} -which follows the link. - -The @code{lstat()} routine is defined by BSD 4.3 and SVR4 -and not included in POSIX 1003.1b-1996. - -@c -@c -@c -@page -@subsection access - Check permissions for a file - -@findex access -@cindex check 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 - -@c -@c -@c -@page -@subsection chmod - Changes file mode. - -@findex chmod -@cindex 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 - -@c -@c -@c -@page -@subsection fchmod - Changes permissions of a file - -@findex fchmod -@cindex 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 - -@c -@c -@c -@page -@subsection getdents - Get directory entries - -@findex getdents -@cindex 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 - -@c -@c -@c -@page -@subsection chown - Changes the owner and/or group of a file. - -@findex chown -@cindex 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. - - - -@c -@c -@c -@page -@subsection utime - Change access and/or modification times of an inode - -@findex utime -@cindex 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 - -@c -@c -@c -@page -@subsection ftruncate - truncate a file to a specified length - -@findex ftruncate -@cindex 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 - -@c -@c -@c -@page -@subsection truncate - truncate a file to a specified length - -@findex truncate -@cindex 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 - -@c -@c -@c -@page -@subsection pathconf - Gets configuration values for files - -@findex pathconf -@cindex 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. - -@c -@c -@c -@page -@subsection fpathconf - Gets configuration values for files - -@findex fpathconf -@cindex 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 - -@c -@c -@c -@page -@subsection mknod - create a directory - -@findex mknod -@cindex 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/gen_size_report b/doc/posix_users/gen_size_report deleted file mode 100644 index 767001c9a0..0000000000 --- a/doc/posix_users/gen_size_report +++ /dev/null @@ -1,190 +0,0 @@ -# -# Hack of a script to generate a very long list which contains -# the size information for every service listed in this manual -# -# This script must be modified by the user to tailor it for their -# environment. This is VERY ugly and could be replaced by something -# nicer in the future if this report style is useful. - -#cpu=sparc -#bsp=erc32 - -#cpu=powerpc -#bsp=mcp750 - -cpu=v850 -bsp=bare -symprefix=_ - -#objdir=/usr1/rtems/build/build-${cpu}-rtems/${cpu}-rtems/c/${bsp}/ -#libc=/opt/rtems/${cpu}-rtems/lib/libc.a -#libm=/opt/rtems/${cpu}-rtems/lib/libm.a -objdir=/usr1/rtems/work/tools-v850/b-rtems/${cpu}-rtems/c/${bsp}/ -libc=/usr2/test-v850/${cpu}-rtems/lib/libc.a -libm=/usr2/test-v850/${cpu}-rtems/lib/libm.a -srcdir=$r/src -docdir=$d -nm=${cpu}-rtems-nm -size=${cpu}-rtems-size -ar=${cpu}-rtems-ar - -# -# All customization should be above this point -# - -check_objs() -{ - for i in *.o - do - ${nm} $i | grep "T ${symprefix}${1}$" >/dev/null - if [ $? -eq 0 ] ; then - echo $i - return 0 - fi - done - return 1 -} -per_manager() -{ - docfile=$1 - shift - subdirs=$* - grep ^@item ${docfile} | grep "@code.* - " | \ - grep -v "@item E" | \ - grep -v "@code{CONFIGURE" | \ - grep -v "@value{RPREFIX" | \ - sed -e 's/@value{DIRPREFIX}/rtems_/' | \ - cut -d'{' -f2 | sed -e 's/}//' | cut -d'-' -f1 >/tmp/XXX.size - - if [ `wc -c </tmp/XXX.size` -eq 1 ] ; then - return - fi - echo "====> `grep ^@chapter ${docfile} | sed -e 's/@chapter //'`" - cat /tmp/XXX.size | while read line - do - # echo $line - found=no - for subd in ${subdirs} - do - if [ ${found} = "no" ] ; then - cd ${objdir}/${subd}/o-optimize/ - objfile=`check_objs $line` - if [ $? -eq 0 ] ; then - found=yes - #echo ${objfile} - objcode=`${size} ${objfile} | tail -1 | cut -f1` - objdata=`${size} ${objfile} | tail -1 | cut -f2` - objbss=`${size} ${objfile} | tail -1 | cut -f3` - objcode=`echo ${objcode}` - objdata=`echo ${objdata}` - objbss=`echo ${objbss}` - echo "${line} - ${objcode}, ${objdata}, ${objbss}" - fi - fi - done - if [ ${found} = "no" ] ; then - echo "$line - macro or not implemented" - fi - - done -} - - -# extract libc -if [ ! -d ${objdir}/newlib_extract/o-optimize ] ; then - mkdir -p ${objdir}/newlib_extract/o-optimize - cd ${objdir}/newlib_extract/o-optimize - list=`${ar} t ${libc}` - for i in $list - do - ${ar} x ${libc} ${i} - done -fi - -# extract libm -if [ ! -d ${objdir}/libm_extract/o-optimize ] ; then - mkdir -p ${objdir}/libm_extract/o-optimize - cd ${objdir}/libm_extract/o-optimize - list=`${ar} t ${libm}` - for i in $list - do - ${ar} x ${libm} ${i} - done -fi - -# grab the size of the Classic API -# -# NOTE: This API is always configured. -# -cd ${docdir}/user -echo -echo "==============================================================" -echo "==============================================================" -echo "==== ====" -echo "==== CLASSIC API SIZE INFORMATION ====" -echo "==== ====" -echo "==============================================================" -echo "==============================================================" -echo -if [ -r ${objdir}/../../../${bsp}/lib/librtems.a ] ; then - for i in *.t - do - per_manager $i exec/rtems/src exec/sapi/src lib/libc - done -else - echo "RTEMS Classic API not configured." -fi - -# Grab the size of the POSIX API -cd ${docdir}/posix_users -echo -echo "==============================================================" -echo "==============================================================" -echo "==== ====" -echo "==== POSIX 1003.1b API SIZE INFORMATION ====" -echo "==== ====" -echo "==============================================================" -echo "==============================================================" -echo -if [ -r ${objdir}/../../../${bsp}/lib/libposix.a ] ; then - for i in `ls -1 *.t | grep -v libc.t | grep -v libm.t` - do - per_manager $i exec/posix/src lib/libc newlib_extract - done -else - echo "POSIX API not configured." -fi - -# Grab the size of the POSIX routines provided by the C Library -cd ${docdir}/posix_users -echo -echo "==============================================================" -echo "==============================================================" -echo "==== ====" -echo "==== LIBC API SIZE INFORMATION ====" -echo "==== ====" -echo "==============================================================" -echo "==============================================================" -echo -for i in libc.t -do - per_manager $i exec/posix/src lib/libc newlib_extract -done - -# Grab the size of the libm routines -cd ${docdir}/posix_users -echo -echo "==============================================================" -echo "==============================================================" -echo "==== ====" -echo "==== LIBM API SIZE INFORMATION ====" -echo "==== ====" -echo "==============================================================" -echo "==============================================================" -echo -for i in libm.t -do - per_manager $i exec/posix/src lib/libc libm_extract -done - - diff --git a/doc/posix_users/io.t b/doc/posix_users/io.t deleted file mode 100644 index 143d174d13..0000000000 --- a/doc/posix_users/io.t +++ /dev/null @@ -1,1274 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@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} - Create an Inter-Process Channel -@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 file complete in-core state with that on disk -@item @code{fdatasync} - Synchronize file in-core data with that on disk -@item @code{sync} - Schedule file system updates -@item @code{mount} - Mount a file system -@item @code{unmount} - Unmount file systems -@item @code{readv} - Vectored read from a file -@item @code{writev} - Vectored write to a file -@item @code{aio_read} - Asynchronous Read -@item @code{aio_write} - Asynchronous Write -@item @code{lio_listio} - List Directed I/O -@item @code{aio_error} - Retrieve Error Status of Asynchronous I/O Operation -@item @code{aio_return} - Retrieve Return Status Asynchronous I/O Operation -@item @code{aio_cancel} - Cancel Asynchronous I/O Request -@item @code{aio_suspend} - Wait for Asynchronous I/O Request -@item @code{aio_fsync} - Asynchronous File Synchronization -@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. - -@c -@c -@c -@page -@subsection pipe - Create an Inter-Process Channel - -@findex pipe -@cindex create an inter - -@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. - -@c -@c -@c -@page -@subsection dup - Duplicates an open file descriptor - -@findex dup -@cindex 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 - -@c -@c -@c -@page -@subsection dup2 - Duplicates an open file descriptor - -@findex dup2 -@cindex 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 - -@c -@c -@c -@page -@subsection close - Closes a file - -@findex close -@cindex 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. - -@c -@c -@c -@page -@subsection read - Reads from a file - -@findex read -@cindex 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 - -@item EINVAL -Bad buffer pointer - -@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 - -@c -@c -@c -@page -@subsection write - Writes to a file - -@findex write -@cindex 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. - -@item EINVAL -Bad buffer pointer - -@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 - -@c -@c -@c -@page -@subsection fcntl - Manipulates an open file descriptor - -@findex fcntl -@cindex 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}. - -@c -@c -@c -@page -@subsection lseek - Reposition read/write file offset - -@findex lseek -@cindex 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 - -@c -@c -@c -@page -@subsection fsync - Synchronize file complete in-core state with that on disk - -@findex fsync -@cindex synchronize file complete in - -@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 - -@c -@c -@c -@page -@subsection fdatasync - Synchronize file in-core data with that on disk - -@findex fdatasync -@cindex synchronize file in - -@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 - -@c -@c -@c -@page -@subsection sync - Schedule file system updates - -@findex sync -@cindex synchronize file systems - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -void sync(void); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -NONE - -@subheading DESCRIPTION: - -The @code{sync} service causes all information in memory that updates -file systems to be scheduled for writing out to all file systems. - - -@subheading NOTES: - -The writing of data to the file systems is only guaranteed to be -scheduled upon return. It is not necessarily complete upon return -from @code{sync}. - -@c -@c -@c -@page -@subsection mount - Mount a file system - -@findex mount -@cindex mount a file system - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <libio.h> - -int mount( - rtems_filesystem_mount_table_entry_t **mt_entry, - rtems_filesystem_operations_table *fs_ops, - rtems_filesystem_options_t fsoptions, - char *device, - char *mount_point -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EXXX - -@end table - -@subheading DESCRIPTION: - -The @code{mount} routines mounts the filesystem class -which uses the filesystem operations specified by @code{fs_ops} -and @code{fsoptions}. The filesystem is mounted at the directory -@code{mount_point} and the mode of the mounted filesystem is -specified by @code{fsoptions}. If this filesystem class requires -a device, then the name of the device must be specified by @code{device}. - -If this operation succeeds, the mount table entry for the mounted -filesystem is returned in @code{mt_entry}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection unmount - Unmount file systems - -@findex unmount -@cindex unmount file systems - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <libio.h> - -int unmount( - const char *mount_path -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EXXX -@end table - -@subheading DESCRIPTION: - -The @code{unmount} routine removes the attachment of the filesystem specified -by @code{mount_path}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection readv - Vectored read from a file - -@findex readv -@cindex vectored read from a file - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <sys/uio.h> - -ssize_t readv( - int fd, - const struct iovec *iov, - int iovcnt -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -In addition to the errors detected by -@code{Input and Output Primitives Manager read - Reads from a file, read()}, -this routine may return -1 and sets @code{errno} based upon the following -errors: - -@table @b -@item EINVAL -The sum of the @code{iov_len} values in the iov array overflowed an -@code{ssize_t}. - -@item EINVAL -The @code{iovcnt} argument was less than or equal to 0, or greater -than @code{IOV_MAX}. - -@end table - -@subheading DESCRIPTION: - -The @code{readv()} function is equivalent to @code{read()} -except as described here. The @code{readv()} function shall place -the input data into the @code{iovcnt} buffers specified by the -members of the @code{iov} array: @code{iov[0], iov[1], ..., iov[iovcnt-1]}. - -Each @code{iovec} entry specifies the base address and length of an area -in memory where data should be placed. The @code{readv()} function -always fills an area completely before proceeding to the next. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection writev - Vectored write to a file - -@findex writev -@cindex vectored write to a file - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <sys/uio.h> - -ssize_t writev( - int fd, - const struct iovec *iov, - int iovcnt -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -In addition to the errors detected by -@code{Input and Output Primitives Manager write - Write to a file, write()}, -this routine may return -1 and sets @code{errno} based upon the following -errors: - -@table @b -@item EINVAL -The sum of the @code{iov_len} values in the iov array overflowed an -@code{ssize_t}. - -@item EINVAL -The @code{iovcnt} argument was less than or equal to 0, or greater -than @code{IOV_MAX}. - -@end table - -@subheading DESCRIPTION: - -The @code{writev()} function is equivalent to @code{write()}, -except as noted here. The @code{writev()} function gathers output -data from the @code{iovcnt} buffers specified by the members of -the @code{iov array}: @code{iov[0], iov[1], ..., iov[iovcnt-1]}. -The @code{iovcnt} argument is valid if greater than 0 and less -than or equal to @code{IOV_MAX}. - -Each @code{iovec} entry specifies the base address and length of -an area in memory from which data should be written. The @code{writev()} -function always writes a complete area before proceeding to the next. - -If @code{fd} refers to a regular file and all of the @code{iov_len} -members in the array pointed to by @code{iov} are 0, @code{writev()} -returns 0 and has no other effect. For other file types, the behavior -is unspecified by POSIX. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection aio_read - Asynchronous Read - -@findex aio_read -@cindex asynchronous 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. - -@c -@c -@c -@page -@subsection aio_write - Asynchronous Write - -@findex aio_write -@cindex asynchronous 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. - -@c -@c -@c -@page -@subsection lio_listio - List Directed I/O - -@findex lio_listio -@cindex list directed i/o - -@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. - -@c -@c -@c -@page -@subsection aio_error - Retrieve Error Status of Asynchronous I/O Operation - -@findex aio_error -@cindex retrieve error status of asynchronous i/o operation - -@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. - -@c -@c -@c -@page -@subsection aio_return - Retrieve Return Status Asynchronous I/O Operation - -@findex aio_return -@cindex retrieve return status asynchronous i/o operation - -@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. - -@c -@c -@c -@page -@subsection aio_cancel - Cancel Asynchronous I/O Request - -@findex aio_cancel -@cindex cancel asynchronous i/o request - -@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. - -@c -@c -@c -@page -@subsection aio_suspend - Wait for Asynchronous I/O Request - -@findex aio_suspend -@cindex wait for asynchronous i/o request - -@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. - -@c -@c -@c -@page -@subsection aio_fsync - Asynchronous File Synchronization - -@findex aio_fsync -@cindex asynchronous file synchronization - -@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.t b/doc/posix_users/key.t deleted file mode 100644 index dd7a83d729..0000000000 --- a/doc/posix_users/key.t +++ /dev/null @@ -1,208 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Key Manager - -@section Introduction - -The key manager allows for the creation and deletion of Data keys -specific to threads. - -The directives provided by the key manager are: - -@itemize @bullet -@item @code{pthread_key_create} - Create Thread Specific Data Key -@item @code{pthread_key_delete} - Delete Thread Specific Data Key -@item @code{pthread_setspecific} - Set Thread Specific Key Value -@item @code{pthread_getspecific} - Get Thread Specific Key Value -@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 key 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. - -@c -@c -@c -@page -@subsection pthread_key_create - Create Thread Specific Data Key - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_key_create( - pthread_key_t *key, - void (*destructor)( void ) -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EAGAIN -There were not enough resources available to create another key. - -@item ENOMEM -Insufficient memory exists to create the key. - -@end table - -@subheading DESCRIPTION -The pthread_key_create() function shall create a thread-specific data -key visible to all threads in the process. Key values provided by -pthread_key_create() are opaque objects used to locate thread-specific -data. Although the same key value may be used by different threads, the -values bound to the key by pthread_setspecific() are maintained on a -per-thread basis and persist for the life of the calling thread. - -Upon key creation, the value NULL shall be associated with the new key -in all active threads. Upon thread creation, the value NULL shall be -associated with all defined keys in the new thread. - -@subheading NOTES -An optional destructor function may be associated with each key value. -At thread exit, if a key value has a non-NULL destructor pointer, and -the thread has a non-NULL value associated with that key, the value of -the key is set to NULL, and then the function pointed to is called with -the previously associated value as its sole argument. The order of -destructor calls is unspecified if more than one destructor exists for -a thread when it exits. - -@c -@c -@c -@page -@subsection pthread_key_delete - Delete Thread Specific Data Key - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_key_delete( -pthread_key_t key); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The key was invalid - -@end table - -@subheading DESCRIPTION: -The pthread_key_delete() function shall delete a thread-specific data key -previously returned by pthread_key_create(). The thread-specific data -values associated with key need not be NULL at the time pthread_key_delete() -is called. It is the responsibility of the application to free any -application storage or perform any cleanup actions for data structures related -to the deleted key or associated thread-specific data in any -threads; this cleanup can be done either before or after -pthread_key_delete() is called. Any attempt to use key following the call to -pthread_key_delete() results in undefined behavior. - -@subheading NOTES: -The pthread_key_delete() function shall be callable from within -destructor functions. No destructor functions shall be invoked by -pthread_key_delete(). Any destructor function that may have been -associated with key shall no longer be called upon thread exit. - - -@c -@c -@c -@page -@subsection pthread_setspecific - Set Thread Specific Key Value - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_setspecific( -pthread_key_t key, -const void *value -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The specified key is invalid. - -@end table - -@subheading DESCRIPTION: -The pthread_setspecific() function shall associate a thread-specific value -with a key obtained via a previous call to pthread_key_create(). -Different threads may bind different values to the same key. These values -are typically pointers to blocks of dynamically allocated memory that -have been reserved for use by the calling thread. - -@subheading NOTES: -The effect of calling pthread_setspecific() with a key value not obtained -from pthread_key_create() or after key has -been deleted with pthread_key_delete() is undefined. - -pthread_setspecific() may be called from a thread-specific data -destructor function. Calling pthread_setspecific() from a thread-specific -data destructor routine may result either in lost storage (after at least -PTHREAD_DESTRUCTOR_ITERATIONS attempts at destruction) or in an infinite loop. - - -@c -@c -@c -@page -@subsection pthread_getspecific - Get Thread Specific Key Value - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -void *pthread_getspecific( -pthread_key_t key -); -@end example - -@subheading STATUS CODES: -@table @b -@item NULL -There is no thread-specific data associated with the specified key. - -@item non-NULL -The data associated with the specified key. - -@end table - -@subheading DESCRIPTION: -The pthread_getspecific() function shall return the value currently bound to -the specified key on behalf of the calling thread. - -@subheading NOTES: -The effect of calling pthread_getspecific() with a key value not obtained from -pthread_key_create() or after key has -been deleted with pthread_key_delete() is undefined. - -pthread_getspecific() may be called from a thread-specific data destructor -function. A call to pthread_getspecific() for the thread-specific data key -being destroyed shall return the value NULL, unless the value is changed -(after the destructor starts) by a call to pthread_setspecific(). - diff --git a/doc/posix_users/libc.t b/doc/posix_users/libc.t deleted file mode 100644 index e8a312a37e..0000000000 --- a/doc/posix_users/libc.t +++ /dev/null @@ -1,345 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Services Provided by C Library (libc) - -@section Introduction - -This section lists the routines that provided by the Newlib C Library. - -@section Standard Utility Functions (stdlib.h) - -@itemize @bullet -@item @code{abort} - Abnormal termination of a program -@item @code{abs} - Integer absolute value (magnitude) -@item @code{assert} - Macro for Debugging Diagnostics -@item @code{atexit} - Request execution of functions at program exit -@item @code{atof} - String to double or float -@item @code{atoi} - String to integer -@item @code{bsearch} - Binary search -@item @code{calloc} - Allocate space for arrays -@item @code{div} - Divide two integers -@item @code{ecvtbuf} - Double or float to string of digits -@item @code{ecvt} - Double or float to string of digits (malloc result) -@item @code{__env_lock} - Lock environment list for getenv and setenv -@item @code{gvcvt} - Format double or float as string -@item @code{exit} - End program execution -@item @code{getenv} - Look up environment variable -@item @code{labs} - Long integer absolute value (magnitude) -@item @code{ldiv} - Divide two long integers -@item @code{malloc} - Allocate memory -@item @code{realloc} - Reallocate memory -@item @code{free} - Free previously allocated memory -@item @code{mallinfo} - Get information about allocated memory -@item @code{__malloc_lock} - Lock memory pool for malloc and free -@item @code{mbstowcs} - Minimal multibyte string to wide string converter -@item @code{mblen} - Minimal multibyte length -@item @code{mbtowc} - Minimal multibyte to wide character converter -@item @code{qsort} - Sort an array -@item @code{rand} - Pseudo-random numbers -@item @code{strtod} - String to double or float -@item @code{strtol} - String to long -@item @code{strtoul} - String to unsigned long -@item @code{system} - Execute command string -@item @code{wcstombs} - Minimal wide string to multibyte string converter -@item @code{wctomb} - Minimal wide character to multibyte converter -@end itemize - -@section Character Type Macros and Functions (ctype.h) - -@itemize @bullet -@item @code{isalnum} - Alphanumeric character predicate -@item @code{isalpha} - Alphabetic character predicate -@item @code{isascii} - ASCII character predicate -@item @code{iscntrl} - Control character predicate -@item @code{isdigit} - Decimal digit predicate -@item @code{islower} - Lower-case character predicate -@item @code{isprint} - Printable character predicates (isprint, isgraph) -@item @code{ispunct} - Punctuation character predicate -@item @code{isspace} - Whitespace character predicate -@item @code{isupper} - Uppercase character predicate -@item @code{isxdigit} - Hexadecimal digit predicate -@item @code{toascii} - Force integers to ASCII range -@item @code{tolower} - Translate characters to lower case -@item @code{toupper} - Translate characters to upper case -@end itemize - -@section Input and Output (stdio.h) - -@itemize @bullet -@item @code{clearerr} - Clear file or stream error indicator -@item @code{fclose} - Close a file -@item @code{feof} - Test for end of file -@item @code{ferror} - Test whether read/write error has occurred -@item @code{fflush} - Flush buffered file output -@item @code{fgetc} - Get a character from a file or stream -@item @code{fgetpos} - Record position in a stream or file -@item @code{fgets} - Get character string from a file or stream -@item @code{fiprintf} - Write formatted output to file (integer only) -@item @code{fopen} - Open a file -@item @code{fdopen} - Turn an open file into a stream -@item @code{fputc} - Write a character on a stream or file -@item @code{fputs} - Write a character string in a file or stream -@item @code{fread} - Read array elements from a file -@item @code{freopen} - Open a file using an existing file descriptor -@item @code{fseek} - Set file position -@item @code{fsetpos} - Restore position of a stream or file -@item @code{ftell} - Return position in a stream or file -@item @code{fwrite} - Write array elements from memory to a file or stream -@item @code{getc} - Get a character from a file or stream (macro) -@item @code{getchar} - Get a character from standard input (macro) -@item @code{gets} - Get character string from standard input (obsolete) -@item @code{iprintf} - Write formatted output (integer only) -@item @code{mktemp} - Generate unused file name -@item @code{perror} - Print an error message on standard error -@item @code{putc} - Write a character on a stream or file (macro) -@item @code{putchar} - Write a character on standard output (macro) -@item @code{puts} - Write a character string on standard output -@item @code{remove} - Delete a file's name -@item @code{rename} - Rename a file -@item @code{rewind} - Reinitialize a file or stream -@item @code{setbuf} - Specify full buffering for a file or stream -@item @code{setvbuf} - Specify buffering for a file or stream -@item @code{siprintf} - Write formatted output (integer only) -@item @code{printf} - Write formatted output -@item @code{scanf} - Scan and format input -@item @code{tmpfile} - Create a temporary file -@item @code{tmpnam} - Generate name for a temporary file -@item @code{vprintf} - Format variable argument list -@end itemize - -@section Strings and Memory (string.h) - -@itemize @bullet -@item @code{bcmp} - Compare two memory areas -@item @code{bcopy} - Copy memory regions -@item @code{bzero} - Initialize memory to zero -@item @code{index} - Search for character in string -@item @code{memchr} - Find character in memory -@item @code{memcmp} - Compare two memory areas -@item @code{memcpy} - Copy memory regions -@item @code{memmove} - Move possibly overlapping memory -@item @code{memset} - Set an area of memory -@item @code{rindex} - Reverse search for character in string -@item @code{strcasecmp} - Compare strings ignoring case -@item @code{strcat} - Concatenate strings -@item @code{strchr} - Search for character in string -@item @code{strcmp} - Character string compare -@item @code{strcoll} - Locale specific character string compare -@item @code{strcpy} - Copy string -@item @code{strcspn} - Count chars not in string -@item @code{strerror} - Convert error number to string -@item @code{strlen} - Character string length -@item @code{strlwr} - Convert string to lower case -@item @code{strncasecmp} - Compare strings ignoring case -@item @code{strncat} - Concatenate strings -@item @code{strncmp} - Character string compare -@item @code{strncpy} - Counted copy string -@item @code{strpbrk} - Find chars in string -@item @code{strrchr} - Reverse search for character in string -@item @code{strspn} - Find initial match -@item @code{strstr} - Find string segment -@item @code{strtok} - Get next token from a string -@item @code{strupr} - Convert string to upper case -@item @code{strxfrm} - Transform string -@end itemize - -@section Signal Handling (signal.h) - -@itemize @bullet -@item @code{raise} - Send a signal -@item @code{signal} - Specify handler subroutine for a signal -@end itemize - -@section Time Functions (time.h) - -@itemize @bullet -@item @code{asctime} - Format time as string -@item @code{clock} - Cumulative processor time -@item @code{ctime} - Convert time to local and format as string -@item @code{difftime} - Subtract two times -@item @code{gmtime} - Convert time to UTC (GMT) traditional representation -@item @code{localtime} - Convert time to local representation -@item @code{mktime} - Convert time to arithmetic representation -@item @code{strftime} - Flexible calendar time formatter -@item @code{time} - Get current calendar time (as single number) -@end itemize - -@section Locale (locale.h) - -@itemize @bullet -@item @code{setlocale} - Select or query locale -@end itemize - -@section Reentrant Versions of Functions - - -@itemize @bullet -@item Equivalent for errno variable: - -@itemize @bullet -@item @code{errno_r} - XXX -@end itemize - -@item Locale functions: - -@itemize @bullet -@item @code{localeconv_r} - XXX -@item @code{setlocale_r} - XXX -@end itemize - -@item Equivalents for stdio variables: - -@itemize @bullet -@item @code{stdin_r} - XXX -@item @code{stdout_r} - XXX -@item @code{stderr_r} - XXX -@end itemize - -@item Stdio functions: - -@itemize @bullet -@item @code{fdopen_r} - XXX -@item @code{perror_r} - XXX -@item @code{tempnam_r} - XXX -@item @code{fopen_r} - XXX -@item @code{putchar_r} - XXX -@item @code{tmpnam_r} - XXX -@item @code{getchar_r} - XXX -@item @code{puts_r} - XXX -@item @code{tmpfile_r} - XXX -@item @code{gets_r} - XXX -@item @code{remove_r} - XXX -@item @code{vfprintf_r} - XXX -@item @code{iprintf_r} - XXX -@item @code{rename_r} - XXX -@item @code{vsnprintf_r} - XXX -@item @code{mkstemp_r} - XXX -@item @code{snprintf_r} - XXX -@item @code{vsprintf_r} - XXX -@item @code{mktemp_t} - XXX -@item @code{sprintf_r} - XXX -@end itemize - -@item Signal functions: - -@itemize @bullet -@item @code{init_signal_r} - XXX -@item @code{signal_r} - XXX -@item @code{kill_r} - XXX -@item @code{_sigtramp_r} - XXX -@item @code{raise_r} - XXX -@end itemize - -@item Stdlib functions: - -@itemize @bullet -@item @code{calloc_r} - XXX -@item @code{mblen_r} - XXX -@item @code{srand_r} - XXX -@item @code{dtoa_r} - XXX -@item @code{mbstowcs_r} - XXX -@item @code{strtod_r} - XXX -@item @code{free_r} - XXX -@item @code{mbtowc_r} - XXX -@item @code{strtol_r} - XXX -@item @code{getenv_r} - XXX -@item @code{memalign_r} - XXX -@item @code{strtoul_r} - XXX -@item @code{mallinfo_r} - XXX -@item @code{mstats_r} - XXX -@item @code{system_r} - XXX -@item @code{malloc_r} - XXX -@item @code{rand_r} - XXX -@item @code{wcstombs_r} - XXX -@item @code{malloc_r} - XXX -@item @code{realloc_r} - XXX -@item @code{wctomb_r} - XXX -@item @code{malloc_stats_r} - XXX -@item @code{setenv_r} - XXX -@end itemize - -@item String functions: - -@itemize @bullet -@item @code{strtok_r} - XXX -@end itemize - -@item System functions: - -@itemize @bullet -@item @code{close_r} - XXX -@item @code{link_r} - XXX -@item @code{unlink_r} - XXX -@item @code{execve_r} - XXX -@item @code{lseek_r} - XXX -@item @code{wait_r} - XXX -@item @code{fcntl_r} - XXX -@item @code{open_r} - XXX -@item @code{write_r} - XXX -@item @code{fork_r} - XXX -@item @code{read_r} - XXX -@item @code{fstat_r} - XXX -@item @code{sbrk_r} - XXX -@item @code{gettimeofday_r} - XXX -@item @code{stat_r} - XXX -@item @code{getpid_r} - XXX -@item @code{times_r} - XXX -@end itemize - -@item Time function: - -@itemize @bullet -@item @code{asctime_r} - XXX -@end itemize - -@end itemize - -@section Miscellaneous Macros and Functions - - -@itemize @bullet -@item @code{unctrl} - Return printable representation of a character -@end itemize - -@section Variable Argument Lists - - -@itemize @bullet - -@item Stdarg (stdarg.h): -@itemize @bullet -@item @code{va_start} - XXX -@item @code{va_arg} - XXX -@item @code{va_end} - XXX -@end itemize - -@item Vararg (varargs.h): -@itemize @bullet -@item @code{va_alist} - XXX -@item @code{va_start-trad} - XXX -@item @code{va_arg-trad} - XXX -@item @code{va_end-trad} - XXX -@end itemize -@end itemize - -@section Reentrant System Calls - -@itemize @bullet -@item @code{open_r} - XXX -@item @code{close_r} - XXX -@item @code{lseek_r} - XXX -@item @code{read_r} - XXX -@item @code{write_r} - XXX -@item @code{fork_r} - XXX -@item @code{wait_r} - XXX -@item @code{stat_r} - XXX -@item @code{fstat_r} - XXX -@item @code{link_r} - XXX -@item @code{unlink_r} - XXX -@item @code{sbrk_r} - XXX -@end itemize - - diff --git a/doc/posix_users/libm.t b/doc/posix_users/libm.t deleted file mode 100644 index c5820c4d80..0000000000 --- a/doc/posix_users/libm.t +++ /dev/null @@ -1,55 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Services Provided by the Math Library (libm) - -@section Introduction - -This section lists the routines that provided by the Newlib Math Library -(libm). - -@section Standard Math Functions (math.h) - -@itemize @bullet -@item @code{acos} - Arccosine -@item @code{acosh} - Inverse hyperbolic cosine -@item @code{asin} - Arcsine -@item @code{asinh} - Inverse hyperbolic sine -@item @code{atan} - Arctangent -@item @code{atan2} - Arctangent of y/x -@item @code{atanh} - Inverse hyperbolic tangent -@item @code{jN} - Bessel functions (jN and yN) -@item @code{cbrt} - Cube root -@item @code{copysign} - Sign of Y and magnitude of X -@item @code{cosh} - Hyperbolic cosine -@item @code{erf} - Error function (erf and erfc) -@item @code{exp} - Exponential -@item @code{expm1} - Exponential of x and - 1 -@item @code{fabs} - Absolute value (magnitude) -@item @code{floor} - Floor and ceiling (floor and ceil) -@item @code{fmod} - Floating-point remainder (modulo) -@item @code{frexp} - Split floating-point number -@item @code{gamma} - Logarithmic gamma function -@item @code{hypot} - Distance from origin -@item @code{ilogb} - Get exponent -@item @code{infinity} - Floating infinity -@item @code{isnan} - Check type of number -@item @code{ldexp} - Load exponent -@item @code{log} - Natural logarithms -@item @code{log10} - Base 10 logarithms -@item @code{log1p} - Log of 1 + X -@item @code{matherr} - Modifiable math error handler -@item @code{modf} - Split fractional and integer parts -@item @code{nan} - Floating Not a Number -@item @code{nextafter} - Get next representable number -@item @code{pow} - X to the power Y -@item @code{remainder} - remainder of X divided by Y -@item @code{scalbn} - scalbn -@item @code{sin} - Sine or cosine (sin and cos) -@item @code{sinh} - Hyperbolic sine -@item @code{sqrt} - Positive square root -@item @code{tan} - Tangent -@item @code{tanh} - Hyperbolic tangent -@end itemize diff --git a/doc/posix_users/memorymgmt.t b/doc/posix_users/memorymgmt.t deleted file mode 100644 index 5a5e03642a..0000000000 --- a/doc/posix_users/memorymgmt.t +++ /dev/null @@ -1,372 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@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} - Lock the Address Space of a Process -@item @code{munlockall} - Unlock the Address Space of a Process -@item @code{mlock} - Lock a Range of the Process Address Space -@item @code{munlock} - Unlock a Range of the Process Address Space -@item @code{mmap} - Map Process Addresses to a Memory Object -@item @code{munmap} - Unmap Previously Mapped Addresses -@item @code{mprotect} - Change Memory Protection -@item @code{msync} - Memory Object Synchronization -@item @code{shm_open} - Open a Shared Memory Object -@item @code{shm_unlink} - Remove a Shared Memory Object -@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. - -@c -@c -@c -@page -@subsection mlockall - Lock the Address Space of a Process - -@findex mlockall -@cindex lock the address space of a process - -@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: - -@c -@c -@c -@page -@subsection munlockall - Unlock the Address Space of a Process - -@findex munlockall -@cindex unlock the address space of a process - -@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: - -@c -@c -@c -@page -@subsection mlock - Lock a Range of the Process Address Space - -@findex mlock -@cindex lock a range of the process address space - -@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: - -@c -@c -@c -@page -@subsection munlock - Unlock a Range of the Process Address Space - -@findex munlock -@cindex unlock a range of the process address space - -@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: - -@c -@c -@c -@page -@subsection mmap - Map Process Addresses to a Memory Object - -@findex mmap -@cindex map process addresses to a memory object - -@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: - -@c -@c -@c -@page -@subsection munmap - Unmap Previously Mapped Addresses - -@findex munmap -@cindex unmap previously mapped addresses - -@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: - -@c -@c -@c -@page -@subsection mprotect - Change Memory Protection - -@findex mprotect -@cindex change memory protection - -@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: - -@c -@c -@c -@page -@subsection msync - Memory Object Synchronization - -@findex msync -@cindex memory object synchronization - -@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: - -@c -@c -@c -@page -@subsection shm_open - Open a Shared Memory Object - -@findex shm_open -@cindex open a shared memory object - -@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: - -@c -@c -@c -@page -@subsection shm_unlink - Remove a Shared Memory Object - -@findex shm_unlink -@cindex remove a shared memory object - -@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 deleted file mode 100644 index 9e63f7f440..0000000000 --- a/doc/posix_users/message.t +++ /dev/null @@ -1,692 +0,0 @@ -@c -@c COPYRIGHT(c) 1988-2002. -@c On-Line Applications Research Corporation(OAR). -@c All rights reserved. - -@chapter Message Passing Manager - -@section Introduction - -The message passing manager is the means to provide communication and -synchronization capabilities using POSIX message queues. - -The directives provided by the message passing manager are: - -@itemize @bullet -@item @code{mq_open} - Open a Message Queue -@item @code{mq_close} - Close a Message Queue -@item @code{mq_unlink} - Remove a Message Queue -@item @code{mq_send} - Send a Message to a Message Queue -@item @code{mq_receive} - Receive a Message from a Message Queue -@item @code{mq_notify} - Notify Process that a Message is Available -@item @code{mq_setattr} - Set Message Queue Attributes -@item @code{mq_getattr} - Get Message Queue Attributes -@end itemize - -@section Background - -@subsection Theory - -Message queues are named objects that operate with readers and writers. -In addition, a message queue is a priority queue of discrete messages. -POSIX message queues offer a certain, basic amount of application access -to, and control over, the message queue geometry that can be changed. - -@subsection Messages - -A message is a variable length buffer where information can be stored to -support communication. The length of the message and the information -stored in that message are user-defined and can be actual data, -pointer(s), or empty. There is a maximum acceptable length for a message -that is associated with each message queue. - -@subsection Message Queues - -Message queues are named objects similar to the pipes of POSIX. They are -a means of communicating data between multiple processes and for passing -messages among tasks and ISRs. Message queues can contain a variable -number of messages from 0 to an upper limit that is user defined. The -maximum length of the message can be set on a per message queue basis. -Normally messages are sent and received from the message queue in FIFO -order. However, messages can also be prioritized and a priority queue -established for the passing of messages. Synchronization is needed when a -task waits for a message to arrive at a queue. Also, a task may poll a -queue for the arrival of a message. - -@findex mqd_t -The message queue descriptor @code{mqd_t} represents the message queue. It is -passed as an argument to all of the message queue functions. - -@subsection Building a Message Queue Attribute Set - -The mq_attr structure is used to define the characteristics of the message -queue. - -@findex mq_attr -@example -@group -typedef struct mq_attr@{ - long mq_flags; - long mq_maxmsg; - long mq_msgsize; - long mq_curmsgs; -@}; -@end group -@end example - -All of these attributes are set when the message queue is created using -mq_open. The mq_flags field is not used in the creation of a message -queue, it is only used by mq_setattr and mq_getattr. The structure -mq_attr is passed as an argument to mq_setattr and mq_getattr. - -The mq_flags contain information affecting the behavior of the message -queue. The O_NONBLOCK mq_flag is the only flag that is defined. In -mq_setattr, the mq_flag can be set to dynamically change the blocking and -non-blocking behavior of the message queue. If the non-block flag is set -then the message queue is non-blocking, and requests to send and receive -messages do not block waiting for resources. For a blocking message -queue, a request to send might have to wait for an empty message queue, -and a request to receive might have to wait for a message to arrive on the -queue. Both mq_maxmsg and mq_msgsize affect the sizing of the message -queue. mq_maxmsg specifies how many messages the queue can hold at any -one time. mq_msgsize specifies the size of any one message on the queue. -If either of these limits is exceeded, an error message results. - -Upon return from mq_getattr, the mq_curmsgs is set according to the -current state of the message queue. This specifies the number of messages -currently on the queue. - -@subsection Notification of a Message on the Queue - -Every message queue has the ability to notify one (and only one) process -whenever the queue's state changes from empty (0 messages) to nonempty. -This means that the process does not have to block or constantly poll -while it waits for a message. By calling mq_notify, you can attach a -notification request to a message queue. When a message is received by an -empty queue, if there are no processes blocked and waiting for the -message, then the queue notifies the requesting process of a message -arrival. There is only one signal sent by the message queue, after that -the notification request is de-registered and another process can attach -its notification request. After receipt of a notification, a process must -re-register if it wishes to be notified again. - -If there is a process blocked and waiting for the message, that process -gets the message, and notification is not sent. It is also possible for -another process to receive the message after the notification is sent but -before the notified process has sent its receive request. - -Only one process can have a notification request attached to a message -queue at any one time. If another process attempts to register a -notification request, it fails. You can de-register for a message queue -by passing a NULL to mq_notify, this removes any notification request -attached to the queue. Whenever the message queue is closed, all -notification attachments are removed. - -@subsection POSIX Interpretation Issues - -There is one significant point of interpretation related to -the RTEMS implementation of POSIX message queues: - -@cite{What happens to threads already blocked on a message queue when the -mode of that same message queue is changed from blocking to non-blocking?} - - -The RTEMS POSIX implementation decided to unblock all waiting tasks -with an @code{EAGAIN} status just as if a non-blocking version of -the same operation had returned unsatisfied. This case is not -discussed in the POSIX standard and other implementations may have -chosen alternative behaviors. - -@section Operations - -@subsection Opening or Creating a Message Queue - -If the message queue already exists, mq_open() opens it, if the message -queue does not exist, mq_open() creates it. When a message queue is -created, the geometry of the message queue is contained in the attribute -structure that is passed in as an argument. This includes mq_msgsize that -dictates the maximum size of a single message, and the mq_maxmsg that -dictates the maximum number of messages the queue can hold at one time. -The blocking or non-blocking behavior of the queue can also specified. - -@subsection Closing a Message Queue - -The mq_close() function is used to close the connection made to a message -queue that was made during mq_open. The message queue itself and the -messages on the queue are persistent and remain after the queue is closed. - -@subsection Removing a Message Queue - -The mq_unlink() function removes the named message queue. If the message -queue is not open when mq_unlink is called, then the queue is immediately -eliminated. Any messages that were on the queue are lost, and the queue -can not be opened again. If processes have the queue open when mq_unlink -is called, the removal of the queue is delayed until the last process -using the queue has finished. However, the name of the message queue is -removed so that no other process can open it. - -@subsection Sending a Message to a Message Queue - -The mq_send() function adds the message in priority order to the message -queue. Each message has an assigned a priority. The highest priority -message is be at the front of the queue. - -The maximum number of messages that a message queue may accept is -specified at creation by the mq_maxmsg field of the attribute structure. -If this amount is exceeded, the behavior of the process is determined -according to what oflag was used when the message queue was opened. If -the queue was opened with O_NONBLOCK flag set, the process does not block, -and an error is returned. If the O_NONBLOCK flag was not set, the process -does block and wait for space on the queue. - -@subsection Receiving a Message from a Message Queue - -The mq_receive() function is used to receive the oldest of the highest -priority message(s) from the message queue specified by mqdes. The -messages are received in FIFO order within the priorities. The received -message's priority is stored in the location referenced by the msg_prio. -If the msg_prio is a NULL, the priority is discarded. The message is -removed and stored in an area pointed to by msg_ptr whose length is of -msg_len. The msg_len must be at least equal to the mq_msgsize attribute -of the message queue. - -The blocking behavior of the message queue is set by O_NONBLOCK at mq_open -or by setting O_NONBLOCK in mq_flags in a call to mq_setattr. If this is -a blocking queue, the process does block and wait on an empty queue. If -this a non-blocking queue, the process does not block. Upon successful -completion, mq_receive returns the length of the selected message in bytes -and the message is removed from the queue. - -@subsection Notification of Receipt of a Message on an Empty Queue - -The mq_notify() function registers the calling process to be notified of -message arrival at an empty message queue. Every message queue has the -ability to notify one (and only one) process whenever the queue's state -changes from empty (0 messages) to nonempty. This means that the process -does not have to block or constantly poll while it waits for a message. -By calling mq_notify, a notification request is attached to a message -queue. When a message is received by an empty queue, if there are no -processes blocked and waiting for the message, then the queue notifies the -requesting process of a message arrival. There is only one signal sent by -the message queue, after that the notification request is de-registered -and another process can attach its notification request. After receipt of -a notification, a process must re-register if it wishes to be notified -again. - -If there is a process blocked and waiting for the message, that process -gets the message, and notification is not sent. Only one process can have -a notification request attached to a message queue at any one time. If -another process attempts to register a notification request, it fails. -You can de-register for a message queue by passing a NULL to mq_notify, -this removes any notification request attached to the queue. Whenever the -message queue is closed, all notification attachments are removed. - -@subsection Setting the Attributes of a Message Queue - -The mq_setattr() function is used to set attributes associated with the -open message queue description referenced by the message queue descriptor -specified by mqdes. The *omqstat represents the old or previous -attributes. If omqstat is non-NULL, the function mq_setattr() stores, in -the location referenced by omqstat, the previous message queue attributes -and the current queue status. These values are the same as would be -returned by a call to mq_getattr() at that point. - -There is only one mq_attr.mq_flag that can be altered by this call. This -is the flag that deals with the blocking and non-blocking behavior of the -message queue. If the flag is set then the message queue is non-blocking, -and requests to send or receive do not block while waiting for resources. -If the flag is not set, then message send and receive may involve waiting -for an empty queue or waiting for a message to arrive. - -@subsection Getting the Attributes of a Message Queue - -The mq_getattr() function is used to get status information and attributes -of the message queue associated with the message queue descriptor. The -results are returned in the mq_attr structure referenced by the mqstat -argument. All of these attributes are set at create time, except the -blocking/non-blocking behavior of the message queue which can be -dynamically set by using mq_setattr. The attribute mq_curmsg is set to -reflect the number of messages on the queue at the time that mq_getattr -was called. - -@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. - -@c -@c -@c -@page -@subsection mq_open - Open a Message Queue - -@findex mq_open -@cindex open a message queue - -@subheading CALLING SEQUENCE: - -@example -#include <mqueue.h> - -mqd_t mq_open( - const char *name, - int oflag, - mode_t mode, - struct mq_attr *attr -); -@end example - -@subheading STATUS CODES: - -@code{EACCES} - Either the message queue exists and the permissions -requested in oflags were denied, or the message does not exist and -permission to create one is denied. - -@code{EEXIST} - You tried to create a message queue that already exists. - -@code{EINVAL} - An inappropriate name was given for the message queue, or -the values of mq-maxmsg or mq_msgsize were less than 0. - -@code{ENOENT} - The message queue does not exist, and you did not specify -to create it. - -@code{EINTR} - The call to mq_open was interrupted by a signal. - -@code{EMFILE} - The process has too many files or message queues open. -This is a process limit error. - -@code{ENFILE} - The system has run out of resources to support more open -message queues. This is a system error. - -@code{ENAMETOOLONG} - mq_name is too long. - -@subheading DESCRIPTION: - -The mq_open () function establishes the connection between a process and a -message queue with a message queue descriptor. If the message queue -already exists, mq_open opens it, if the message queue does not exist, -mq_open creates it. Message queues can have multiple senders and -receivers. If mq_open is successful, the function returns a message queue -descriptor. Otherwise, the function returns a -1 and sets 'errno' to -indicate the error. - -The name of the message queue is used as an argument. For the best of -portability, the name of the message queue should begin with a "/" and no -other "/" should be in the name. Different systems interpret the name in -different ways. - -The oflags contain information on how the message is opened if the queue -already exists. This may be O_RDONLY for read only, O_WRONLY for write -only, of O_RDWR, for read and write. - -In addition, the oflags contain information needed in the creation of a -message queue. @code{O_NONBLOCK} - If the non-block flag is set then the -message queue is non-blocking, and requests to send and receive messages -do not block waiting for resources. If the flag is not set then the -message queue is blocking, and a request to send might have to wait for an -empty message queue. Similarly, a request to receive might have to wait -for a message to arrive on the queue. @code{O_CREAT} - This call specifies -that the call the mq_open is to create a new message queue. In this case -the mode and attribute arguments of the function call are utilized. The -message queue is created with a mode similar to the creation of a file, -read and write permission creator, group, and others. - -The geometry of the message queue is contained in the attribute structure. -This includes mq_msgsize that dictates the maximum size of a single -message, and the mq_maxmsg that dictates the maximum number of messages -the queue can hold at one time. If a NULL is used in the mq_attr -argument, then the message queue is created with implementation defined -defaults. @code{O_EXCL} - is always set if O_CREAT flag is set. If the -message queue already exists, O_EXCL causes an error message to be -returned, otherwise, the new message queue fails and appends to the -existing one. - -@subheading NOTES: - -The mq_open () function does not add or remove messages from the queue. -When a new message queue is being created, the mq_flag field of the -attribute structure is not used. - -@c -@c -@c -@page -@subsection mq_close - Close a Message Queue - -@findex mq_close -@cindex close a message queue - -@subheading CALLING SEQUENCE: - -@example -#include <mqueue.h> - -int mq_close( - mqd_t mqdes -); -@end example - -@subheading STATUS CODES: - -@code{EINVAL} - The descriptor does not represent a valid open message -queue - -@subheading DESCRIPTION: - -The mq_close function removes the association between the message queue -descriptor, mqdes, and its message queue. If mq_close() is successfully -completed, the function returns a value of zero; otherwise, the function -returns a value of -1 and sets errno to indicate the error. - -@subheading NOTES: - -If the process had successfully attached a notification request to the -message queue via mq_notify, this attachment is removed, and the message -queue is available for another process to attach for notification. -mq_close has no effect on the contents of the message queue, all the -messages that were in the queue remain in the queue. - -@c -@c -@c -@page -@subsection mq_unlink - Remove a Message Queue - -@findex mq_unlink -@cindex remove a message queue - -@subheading CALLING SEQUENCE: - -@example -#include <mqueue.h> - -int mq_unlink( - const char *name -); -@end example - -@subheading STATUS CODES: - -@code{EINVAL} - The descriptor does not represent a valid message queue - -@subheading DESCRIPTION: - -The mq_unlink() function removes the named message queue. If the message -queue is not open when mq_unlink is called, then the queue is immediately -eliminated. Any messages that were on the queue are lost, and the queue -can not be opened again. If processes have the queue open when mq_unlink -is called, the removal of the queue is delayed until the last process -using the queue has finished. However, the name of the message queue is -removed so that no other process can open it. Upon successful completion, -the function returns a value of zero. Otherwise, the named message queue -is not changed by this function call, and the function returns a value of --1 and sets errno to indicate the error. - -@subheading NOTES: - -Calls to mq_open() to re-create the message queue may fail until the -message queue is actually removed. However, the mq_unlink() call need not -block until all references have been closed; it may return immediately. - -@c -@c -@c -@page -@subsection mq_send - Send a Message to a Message Queue - -@findex mq_send -@cindex send a message to a message queue - -@subheading CALLING SEQUENCE: - -@example -#include<mqueue.h> -int mq_send( - mqd_t mqdes, - const char *msg_ptr, - size_t msg_len, - unsigned int msg_prio -); -@end example - -@subheading STATUS CODES: - -@code{EBADF} - The descriptor does not represent a valid message queue, or the queue was opened for read only O_RDONLY -@code{EINVAL} - The value of msg_prio was greater than the MQ_PRIO_MAX. -@code{EMSGSIZE} - The msg_len is greater than the mq_msgsize attribute of the message queue -@code{EAGAIN} - The message queue is non-blocking, and there is no room on the queue for another message as specified by the mq_maxmsg. -@code{EINTR} - The message queue is blocking. While the process was waiting for free space on the queue, a signal arrived that interrupted the wait. - -@subheading DESCRIPTION: - -The mq_send() function adds the message pointed to by the argument msg_ptr -to the message queue specified by mqdes. Each message is assigned a -priority , from 0 to MQ_PRIO_MAX. MQ_PRIO_MAX is defined in <limits.h> and -must be at least 32. Messages are added to the queue in order of their -priority. The highest priority message is at the front of the queue. - -The maximum number of messages that a message queue may accept is -specified at creation by the mq_maxmsg field of the attribute structure. -If this amount is exceeded, the behavior of the process is determined -according to what oflag was used when the message queue was opened. If -the queue was opened with O_NONBLOCK flag set, then the EAGAIN error is -returned. If the O_NONBLOCK flag was not set, the process blocks and -waits for space on the queue, unless it is interrupted by a signal. - -Upon successful completion, the mq_send () function returns a value of -zero. Otherwise, no message is enqueued, the function returns -1, and -errno is set to indicate the error. - -@subheading NOTES: - -If the specified message queue is not full, mq_send inserts the message at -the position indicated by the msg_prio argument. - -@c -@c -@c -@page -@subsection mq_receive - Receive a Message from a Message Queue - -@findex mq_receive -@cindex receive a message from a message queue - -@subheading CALLING SEQUENCE: - -@example -#include <mqueue.h> - -size_t mq_receive( - mqd_t mqdes, - char *msg_ptr, - size_t msg_len, - unsigned int *msg_prio -); -@end example - -@subheading STATUS CODES: - -@code{EBADF} - The descriptor does not represent a valid message queue, or the queue was opened for write only O_WRONLY -@code{EMSGSIZE} - The msg_len is less than the mq_msgsize attribute of the message queue -@code{EAGAIN} - The message queue is non-blocking, and the queue is empty -@code{EINTR} - The message queue is blocking. While the process was waiting for a message to arrive on the queue, a signal arrived that interrupted the wait. - -@subheading DESCRIPTION: - -The mq_receive function is used to receive the oldest of the highest -priority message(s) from the message queue specified by mqdes. The -messages are received in FIFO order within the priorities. The received -message's priority is stored in the location referenced by the msg_prio. -If the msg_prio is a NULL, the priority is discarded. The message is -removed and stored in an area pointed to by msg_ptr whose length is of -msg_len. The msg_len must be at least equal to the mq_msgsize attribute -of the message queue. - -The blocking behavior of the message queue is set by O_NONBLOCK at mq_open -or by setting O_NONBLOCK in mq_flags in a call to mq_setattr. If this is -a blocking queue, the process blocks and waits on an empty queue. If this -a non-blocking queue, the process does not block. - -Upon successful completion, mq_receive returns the length of the selected -message in bytes and the message is removed from the queue. Otherwise, no -message is removed from the queue, the function returns a value of -1, and -sets errno to indicate the error. - -@subheading NOTES: - -If the size of the buffer in bytes, specified by the msg_len argument, is -less than the mq_msgsize attribute of the message queue, the function -fails and returns an error - -@c -@c -@c -@page -@subsection mq_notify - Notify Process that a Message is Available - -@findex mq_notify -@cindex notify process that a message is available - -@subheading CALLING SEQUENCE: - -@example -#include <mqueue.h> - -int mq_notify( - mqd_t mqdes, - const struct sigevent *notification -); -@end example - -@subheading STATUS CODES: - -@code{EBADF} - The descriptor does not refer to a valid message queue -@code{EBUSY} - A notification request is already attached to the queue - -@subheading DESCRIPTION: - -If the argument notification is not NULL, this function registers the -calling process to be notified of message arrival at an empty message -queue associated with the specified message queue descriptor, mqdes. - -Every message queue has the ability to notify one (and only one) process -whenever the queue's state changes from empty (0 messages) to nonempty. -This means that the process does not have to block or constantly poll -while it waits for a message. By calling mq_notify, a notification -request is attached to a message queue. When a message is received by an -empty queue, if there are no processes blocked and waiting for the -message, then the queue notifies the requesting process of a message -arrival. There is only one signal sent by the message queue, after that -the notification request is de-registered and another process can attach -its notification request. After receipt of a notification, a process must -re-register if it wishes to be notified again. - -If there is a process blocked and waiting for the message, that process -gets the message, and notification is not be sent. Only one process can -have a notification request attached to a message queue at any one time. -If another process attempts to register a notification request, it fails. -You can de-register for a message queue by passing a NULL to mq_notify; -this removes any notification request attached to the queue. Whenever the -message queue is closed, all notification attachments are removed. - -Upon successful completion, mq_notify returns a value of zero; otherwise, -the function returns a value of -1 and sets errno to indicate the error. - -@subheading NOTES: - -It is possible for another process to receive the message after the notification is sent but before the notified process has sent its receive request. - -@c -@c -@c -@page -@subsection mq_setattr - Set Message Queue Attributes - -@findex mq_setattr -@cindex set message queue attributes - -@subheading CALLING SEQUENCE: - -@example -#include <mqueue.h> - -int mq_setattr( - mqd_t mqdes, - const struct mq_attr *mqstat, - struct mq_attr *omqstat -); -@end example - -@subheading STATUS CODES: - -@code{EBADF} - The message queue descriptor does not refer to a valid, open queue. -@code{EINVAL} - The mq_flag value is invalid. - -@subheading DESCRIPTION: - -The mq_setattr function is used to set attributes associated with the open -message queue description referenced by the message queue descriptor -specified by mqdes. The *omqstat represents the old or previous -attributes. If omqstat is non-NULL, the function mq_setattr() stores, in -the location referenced by omqstat, the previous message queue attributes -and the current queue status. These values are the same as would be -returned by a call to mq_getattr() at that point. - -There is only one mq_attr.mq_flag which can be altered by this call. -This is the flag that deals with the blocking and non-blocking behavior of -the message queue. If the flag is set then the message queue is -non-blocking, and requests to send or receive do not block while waiting -for resources. If the flag is not set, then message send and receive may -involve waiting for an empty queue or waiting for a message to arrive. - -Upon successful completion, the function returns a value of zero and the -attributes of the message queue have been changed as specified. -Otherwise, the message queue attributes is unchanged, and the function -returns a value of -1 and sets errno to indicate the error. - -@subheading NOTES: - -All other fields in the mq_attr are ignored by this call. - -@c -@c -@c -@page -@subsection mq_getattr - Get Message Queue Attributes - -@findex mq_getattr -@cindex get message queue attributes - -@subheading CALLING SEQUENCE: - -@example -#include <mqueue.h> -int mq_getattr( - mqd_t mqdes, - struct mq_attr *mqstat -); -@end example - -@subheading STATUS CODES: - -@code{EBADF} - The message queue descriptor does not refer to a valid, -open message queue. - -@subheading DESCRIPTION: - -The mqdes argument specifies a message queue descriptor. The mq_getattr -function is used to get status information and attributes of the message -queue associated with the message queue descriptor. The results are -returned in the mq_attr structure referenced by the mqstat argument. All -of these attributes are set at create time, except the -blocking/non-blocking behavior of the message queue which can be -dynamically set by using mq_setattr. The attribute mq_curmsg is set to -reflect the number of messages on the queue at the time that mq_getattr -was called. - -Upon successful completion, the mq_getattr function returns zero. -Otherwise, the function returns -1 and sets errno to indicate the error. - -@subheading NOTES: - diff --git a/doc/posix_users/mutex.t b/doc/posix_users/mutex.t deleted file mode 100644 index 47f094dad4..0000000000 --- a/doc/posix_users/mutex.t +++ /dev/null @@ -1,745 +0,0 @@ -@c -@c COPYRIGHT (c) 1989-2008. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Mutex Manager - -@section Introduction - -The mutex manager implements the functionality required of the mutex -manager as defined by POSIX 1003.1b-1996. This standard requires that -a compliant operating system provide the facilties to ensure that -threads can operate with mutual exclusion from one another and -defines the API that must be provided. - -The services provided by the mutex manager are: - -@itemize @bullet -@item @code{pthread_mutexattr_init} - Initialize a Mutex Attribute Set -@item @code{pthread_mutexattr_destroy} - Destroy a Mutex Attribute Set -@item @code{pthread_mutexattr_setprotocol} - Set the Blocking Protocol -@item @code{pthread_mutexattr_getprotocol} - Get the Blocking Protocol -@item @code{pthread_mutexattr_setprioceiling} - Set the Priority Ceiling -@item @code{pthread_mutexattr_getprioceiling} - Get the Priority Ceiling -@item @code{pthread_mutexattr_setpshared} - Set the Visibility -@item @code{pthread_mutexattr_getpshared} - Get the Visibility -@item @code{pthread_mutex_init} - Initialize a Mutex -@item @code{pthread_mutex_destroy} - Destroy a Mutex -@item @code{pthread_mutex_lock} - Lock a Mutex -@item @code{pthread_mutex_trylock} - Poll to Lock a Mutex -@item @code{pthread_mutex_timedlock} - Lock a Mutex with Timeout -@item @code{pthread_mutex_unlock} - Unlock a Mutex -@item @code{pthread_mutex_setprioceiling} - Dynamically Set the Priority Ceiling -@item @code{pthread_mutex_getprioceiling} - Dynamically Get the Priority Ceiling -@end itemize - -@section Background - -@subsection Mutex Attributes - -Mutex attributes are utilized only at mutex creation time. A mutex -attribute structure may be initialized and passed as an argument to -the @code{mutex_init} routine. Note that the priority ceiling of -a mutex may be set at run-time. - -@table @b -@item blocking protcol -is the XXX - -@item priority ceiling -is the XXX - -@item pshared -is the XXX - -@end table - -@subsection PTHREAD_MUTEX_INITIALIZER - -This is a special value that a variable of type @code{pthread_mutex_t} -may be statically initialized to as shown below: - -@example -pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER; -@end example - -This indicates that @code{my_mutex} will be automatically initialized -by an implicit call to @code{pthread_mutex_init} the first time -the mutex is used. - -Note that the mutex will be initialized with default attributes. - -@section Operations - -There is currently no text in this section. - -@section Services - -This section details the mutex manager's services. -A subsection is dedicated to each of this manager's services -and describes the calling sequence, related constants, usage, -and status codes. - -@c -@c -@c -@page -@subsection pthread_mutexattr_init - Initialize a Mutex Attribute Set - -@findex pthread_mutexattr_init -@cindex initialize a mutex attribute set - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutexattr_init( - pthread_mutexattr_t *attr -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_mutexattr_init} routine initializes the mutex attributes -object specified by @code{attr} with the default value for all of the -individual attributes. - -@subheading NOTES: - -XXX insert list of default attributes here. - -@c -@c -@c -@page -@subsection pthread_mutexattr_destroy - Destroy a Mutex Attribute Set - -@findex pthread_mutexattr_destroy -@cindex destroy a mutex attribute set - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutexattr_destroy( - pthread_mutexattr_t *attr -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_mutex_attr_destroy} routine is used to destroy a mutex -attributes object. The behavior of using an attributes object after -it is destroyed is implementation dependent. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection pthread_mutexattr_setprotocol - Set the Blocking Protocol - -@findex pthread_mutexattr_setprotocol -@cindex set the blocking protocol - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutexattr_setprotocol( - pthread_mutexattr_t *attr, - int protocol -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The protocol argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_mutexattr_setprotocol} routine is used to set value of the -@code{protocol} attribute. This attribute controls the order in which -threads waiting on this mutex will receive it. - -The @code{protocol} can be one of the following: - -@table @b - -@item @code{PTHREAD_PRIO_NONE} -in which case blocking order is FIFO. - -@item @code{PTHREAD_PRIO_INHERIT} -in which case blocking order is priority with the priority inheritance -protocol in effect. - -@item @code{PTHREAD_PRIO_PROTECT} -in which case blocking order is priority with the priority ceiling -protocol in effect. - -@end table - -@subheading NOTES: - -There is currently no way to get simple priority blocking ordering -with POSIX mutexes even though this could easily by supported by RTEMS. - -@c -@c -@c -@page -@subsection pthread_mutexattr_getprotocol - Get the Blocking Protocol - -@findex pthread_mutexattr_getprotocol -@cindex get the blocking protocol - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutexattr_getprotocol( - pthread_mutexattr_t *attr, - int *protocol -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The protocol pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_mutexattr_getprotocol} routine is used to obtain -the value of the @code{protocol} attribute. This attribute controls -the order in which threads waiting on this mutex will receive it. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection pthread_mutexattr_setprioceiling - Set the Priority Ceiling - -@findex pthread_mutexattr_setprioceiling -@cindex set the priority ceiling - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutexattr_setprioceiling( - pthread_mutexattr_t *attr, - int prioceiling -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The prioceiling argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_mutexattr_setprioceiling} routine is used to set value of the -@code{prioceiling} attribute. This attribute specifies the priority that -is the ceiling for threads obtaining this mutex. Any task obtaining this -mutex may not be of greater priority that the ceiling. If it is of lower -priority, then its priority will be elevated to @code{prioceiling}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection pthread_mutexattr_getprioceiling - Get the Priority Ceiling - -@findex pthread_mutexattr_getprioceiling -@cindex get the priority ceiling - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutexattr_getprioceiling( - const pthread_mutexattr_t *attr, - int *prioceiling -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The prioceiling pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_mutexattr_getprioceiling} routine is used to obtain the -value of the @code{prioceiling} attribute. This attribute specifies the -priority ceiling for this mutex. - - -@subheading NOTES: - - -NONE -@c -@c -@c -@page -@subsection pthread_mutexattr_setpshared - Set the Visibility - -@findex pthread_mutexattr_setpshared -@cindex set the visibility - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutexattr_setpshared( - pthread_mutexattr_t *attr, - int pshared -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The pshared argument is invalid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_mutexattr_getpshared - Get the Visibility - -@findex pthread_mutexattr_getpshared -@cindex get the visibility - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutexattr_getpshared( - const pthread_mutexattr_t *attr, - int *pshared -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The pshared pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_mutex_init - Initialize a Mutex - -@findex pthread_mutex_init -@cindex initialize a mutex - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutex_init( - pthread_mutex_t *mutex, - const pthread_mutexattr_t *attr -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The specified protocol is invalid. - -@item EAGAIN -The system lacked the necessary resources to initialize another mutex. - -@item ENOMEM -Insufficient memory exists to initialize the mutex. - -@item EBUSY -Attempted to reinialize the object reference by mutex, a previously -initialized, but not yet destroyed. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_mutex_destroy - Destroy a Mutex - -@findex pthread_mutex_destroy -@cindex destroy a mutex - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutex_destroy( - pthread_mutex_t *mutex -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The specified mutex is invalid. - -@item EBUSY -Attempted to destroy the object reference by mutex, while it is locked or -referenced by another thread. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_mutex_lock - Lock a Mutex - -@findex pthread_mutex_lock -@cindex lock a mutex - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutex_lock( - pthread_mutex_t *mutex -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The specified mutex is invalid. - -@item EINVAL -The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the -priority of the calling thread is higher than the current priority -ceiling. - -@item EDEADLK -The current thread already owns the mutex. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_mutex_trylock - Poll to Lock a Mutex - -@findex pthread_mutex_trylock -@cindex poll to lock a mutex - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutex_trylock( - pthread_mutex_t *mutex -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The specified mutex is invalid. - -@item EINVAL -The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the -priority of the calling thread is higher than the current priority -ceiling. - -@item EBUSY -The mutex is already locked. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_mutex_timedlock - Lock a Mutex with Timeout - -@findex pthread_mutex_timedlock -@cindex lock a mutex with timeout - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> -#include <time.h> - -int pthread_mutex_timedlock( - pthread_mutex_t *mutex, - const struct timespec *timeout -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The specified mutex is invalid. - -@item EINVAL -The nanoseconds field of timeout is invalid. - -@item EINVAL -The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the -priority of the calling thread is higher than the current priority -ceiling. - -@item EDEADLK -The current thread already owns the mutex. - -@item ETIMEDOUT -The calling thread was unable to obtain the mutex within the specified -timeout period. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c -@c -@page -@subsection pthread_mutex_unlock - Unlock a Mutex - -@findex pthread_mutex_unlock -@cindex unlock a mutex - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutex_unlock( - pthread_mutex_t *mutex -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The specified mutex is invalid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling - -@findex pthread_mutex_setprioceiling -@cindex dynamically set the priority ceiling - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutex_setprioceiling( - pthread_mutex_t *mutex, - int prioceiling, - int *oldceiling -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The oldceiling pointer parameter is invalid. - -@item EINVAL -The prioceiling parameter is an invalid priority. - -@item EINVAL -The specified mutex is invalid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - -@c -@c -@c -@page -@subsection pthread_mutex_getprioceiling - Get the Current Priority Ceiling - -@findex pthread_mutex_getprioceiling -@cindex get the current priority ceiling - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_mutex_getprioceiling( - pthread_mutex_t *mutex, - int *prioceiling -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The prioceiling pointer parameter is invalid. - -@item EINVAL -The specified mutex is invalid. - -@end table - -@subheading DESCRIPTION: - -@subheading NOTES: - diff --git a/doc/posix_users/posix_users.texi b/doc/posix_users/posix_users.texi deleted file mode 100644 index 31b35b0645..0000000000 --- a/doc/posix_users/posix_users.texi +++ /dev/null @@ -1,151 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename posix_users.info -@setcontentsaftertitlepage -@syncodeindex vr fn -@synindex ky cp -@paragraphindent 0 -@c %**end of header - -@c -@c COPYRIGHT (c) 1989-2013. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@c -@c Master file for the POSIX API User's Guide -@c - -@c Joel's Questions -@c -@c 1. Why does paragraphindent only impact makeinfo? -@c 2. Why does paragraphindent show up in HTML? -@c - -@include version.texi -@include common/setup.texi -@include common/rtems.texi - -@ifset use-ascii -@dircategory RTEMS On-Line Manual -@direntry -* RTEMS Posix API User's Guide: (posix_users). - Posix API User's Guide Plan -@end direntry -@end ifset - -@c variable substitution info: -@c -@c Note: At the moment we do not document the Ada interface but by building -@c in the infrastructure Florist support should be simple to add. -@set is-C -@clear is-Ada -@set LANGUAGE C -@set STRUCTURE structure -@set ROUTINE function -@set OR | -@set RPREFIX RTEMS_ -@set DIRPREFIX rtems_ -@c the language is @value{LANGUAGE} -@c NOTE: don't use underscore in the name -@c - -@c -@c Title Page Stuff -@c - -@c -@c I don't really like having a short title page. --joel -@c -@c @shorttitlepage RTEMS POSIX API User's Guide - -@setchapternewpage odd -@settitle RTEMS POSIX API User's Guide -@titlepage -@finalout - -@title RTEMS POSIX API User's Guide -@subtitle Edition @value{EDITION}, for RTEMS @value{VERSION} -@sp 1 -@subtitle @value{UPDATED} -@author On-Line Applications Research Corporation -@page -@include common/cpright.texi -@end titlepage - -@c This prevents a black box from being printed on "overflow" lines. -@c The alternative is to rework a sentence to avoid this problem. - -@contents - -@ifnottex -@node Top, Preface, (dir), (dir) -@top RTEMS POSIX API User's Guide - -@menu -* Preface:: -* Process Creation and Execution Manager:: -* Signal Manager:: -* Process Environment Manager:: -* Files and Directories Manager:: -* Input and Output Primitives Manager:: -* Device- and Class- Specific Functions Manager:: -* Language-Specific Services for the C Programming Language Manager:: -* System Databases Manager:: -* Semaphore Manager:: -* Mutex Manager:: -* Condition Variable Manager:: -* Memory Management Manager:: -* Scheduler Manager:: -* Clock Manager:: -* Timer Manager:: -* Message Passing Manager:: -* Thread Manager:: -* Key Manager:: -* Thread Cancellation Manager:: -* Services Provided by C Library (libc):: -* Services Provided by the Math Library (libm):: -* Status of Implementation:: -* Command and Variable Index:: -* Concept Index:: -@end menu -@end ifnottex - -@include preface.texi -@include process.texi -@include signal.texi -@include procenv.texi -@include files.texi -@include io.texi -@include device.texi -@include cspecific.texi -@include systemdb.texi -@include semaphores.texi -@include mutex.texi -@include cond.texi -@include memorymgmt.texi -@include sched.texi -@include clock.texi -@include timer.texi -@include message.texi -@include thread.texi -@include key.texi -@include cancel.texi -@include libc.texi -@include libm.texi -@include status.texi -@node Command and Variable Index, Concept Index, , Top -@unnumbered Command and Variable Index - -@c There are currently no Command and Variable Index entries. - -@printindex fn - -@node Concept Index, , Command and Variable Index, Top -@unnumbered Concept Index - -@c There are currently no Concept Index entries. -@printindex cp - -@bye - diff --git a/doc/posix_users/preface.texi b/doc/posix_users/preface.texi deleted file mode 100644 index de3fce0472..0000000000 --- a/doc/posix_users/preface.texi +++ /dev/null @@ -1,35 +0,0 @@ -@c -@c COPYRIGHT (c) 1989-2011. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@node Preface, , Top, Top -@unnumbered Preface - -This is the User's Guide for the POSIX API support -provided in RTEMS. - -The functionality described in this document is based -on the following standards: - -@itemize @bullet - -@item POSIX 1003.1b-1993. - -@item POSIX 1003.1h/D3. - -@item Open Group Single UNIX Specification. - -@end itemize - -Much of the POSIX API standard is actually implemented in the -Cygnus Newlib ANSI C Library. Please refer to documentation on -Newlib for more information on the functionality it supplies. - -This manual is still under construction and improvements -are welcomed from users. - -@unnumberedsec Acknowledgements - -@include common/opengroup_preface_acknowledgement.texi - diff --git a/doc/posix_users/procenv.t b/doc/posix_users/procenv.t deleted file mode 100644 index 074b94b037..0000000000 --- a/doc/posix_users/procenv.t +++ /dev/null @@ -1,961 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Process Environment Manager - -@section Introduction - -The process environment manager is responsible for providing the -functions related to user and group Id management. - -The directives provided by the process environment manager are: - -@itemize @bullet -@item @code{getpid} - Get Process ID -@item @code{getppid} - Get Parent Process ID -@item @code{getuid} - Get User ID -@item @code{geteuid} - Get Effective User ID -@item @code{getgid} - Get Real Group ID -@item @code{getegid} - Get Effective Group ID -@item @code{setuid} - Set User ID -@item @code{setgid} - Set Group ID -@item @code{getgroups} - Get Supplementary Group IDs -@item @code{getlogin} - Get User Name -@item @code{getlogin_r} - Reentrant Get User Name -@item @code{getpgrp} - Get Process Group ID -@item @code{setsid} - Create Session and Set Process Group ID -@item @code{setpgid} - Set Process Group ID for Job Control -@item @code{uname} - Get System Name -@item @code{times} - Get Process Times -@item @code{getenv} - Get Environment Variables -@item @code{setenv} - Set Environment Variables -@item @code{ctermid} - Generate Terminal Pathname -@item @code{ttyname} - Determine Terminal Device Name -@item @code{ttyname_r} - Reentrant Determine Terminal Device Name -@item @code{isatty} - Determine if File Descriptor is Terminal -@item @code{sysconf} - Get Configurable System Variables -@end itemize - -@section Background - -@subsection Users and Groups - -RTEMS provides a single process, multi-threaded execution environment. -In this light, the notion of user and group is somewhat without meaning. -But RTEMS does provide services to provide a synthetic version of -user and group. By default, a single user and group is associated -with the application. Thus unless special actions are taken, -every thread in the application shares the same user and group Id. -The initial rationale for providing user and group Id functionality -in RTEMS was for the filesystem infrastructure to implement -file permission checks. The effective user/group Id capability -has since been used to implement permissions checking by -the @code{ftpd} server. - -In addition to the "real" user and group Ids, a process may -have an effective user/group Id. This allows a process to -function using a more limited permission set for certain operations. - -@subsection User and Group Names - -POSIX considers user and group Ids to be a unique integer that -may be associated with a name. This is usually accomplished -via a file named @code{/etc/passwd} for user Id mapping and -@code{/etc/groups} for group Id mapping. Again, although -RTEMS is effectively a single process and thus single user -system, it provides limited support for user and group -names. When configured with an appropriate filesystem, RTEMS -will access the appropriate files to map user and group Ids -to names. - -If these files do not exist, then RTEMS will synthesize -a minimal version so this family of services return without -error. It is important to remember that a design goal of -the RTEMS POSIX services is to provide useable and -meaningful results even though a full process model -is not available. - -@subsection Environment Variables - -POSIX allows for variables in the run-time environment. These are -name/value pairs that make be dynamically set and obtained by -programs. In a full POSIX environment with command line shell -and multiple processes, environment variables may be set in -one process -- such as the shell -- and inherited by child -processes. In RTEMS, there is only one process and thus -only one set of environment variables across all processes. - - -@section Operations - -@subsection Accessing User and Group Ids - -The user Id associated with the current thread may be obtain -using the @code{getuid()} service. Similarly, the group Id -may be obtained using the @code{getgid()} service. - -@subsection Accessing Environment Variables - -The value associated with an environment variable may be -obtained using the @code{getenv()} service and set using -the @code{putenv()} service. - -@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. - -@c -@c -@c -@page -@subsection getpid - Get Process ID - -@findex getpid -@cindex get process id - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int getpid( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -The process Id is returned. - -@subheading DESCRIPTION: - -This service returns the process Id. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection getppid - Get Parent Process ID - -@findex getppid -@cindex get parent process id - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int getppid( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -The parent process Id is returned. - -@subheading DESCRIPTION: - -This service returns the parent process Id. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection getuid - Get User ID - -@findex getuid -@cindex get user id - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int getuid( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -The effective user Id is returned. - -@subheading DESCRIPTION: - -This service returns the effective user Id. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection geteuid - Get Effective User ID - -@findex geteuid -@cindex get effective user id - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int geteuid( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -The effective group Id is returned. - -@subheading DESCRIPTION: - -This service returns the effective group Id. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection getgid - Get Real Group ID - -@findex getgid -@cindex get real group id - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int getgid( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -The group Id is returned. - -@subheading DESCRIPTION: - -This service returns the group Id. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection getegid - Get Effective Group ID - -@findex getegid -@cindex get effective group id - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int getegid( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -The effective group Id is returned. - -@subheading DESCRIPTION: - -This service returns the effective group Id. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection setuid - Set User ID - -@findex setuid -@cindex set user id - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int setuid( - uid_t uid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -This service returns 0. - -@subheading DESCRIPTION: - -This service sets the user Id to @code{uid}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection setgid - Set Group ID - -@findex setgid -@cindex set group id - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int setgid( - gid_t gid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -This service returns 0. - -@subheading DESCRIPTION: - -This service sets the group Id to @code{gid}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection getgroups - Get Supplementary Group IDs - -@findex getgroups -@cindex get supplementary group ids - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int getgroups( - int gidsetsize, - gid_t grouplist[] -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -NA - -@subheading DESCRIPTION: - -This service is not implemented as RTEMS has no notion of -supplemental groups. - -@subheading NOTES: - -If supported, this routine would only be allowed for -the super-user. - -@c -@c -@c -@page -@subsection getlogin - Get User Name - -@findex getlogin -@cindex get user name - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -char *getlogin( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -Returns a pointer to a string containing the name of the -current user. - -@subheading DESCRIPTION: - -This routine returns the name of the current user. - -@subheading NOTES: - -This routine is not reentrant and subsequent calls to -@code{getlogin()} will overwrite the same buffer. - -@c -@c -@c -@page -@subsection getlogin_r - Reentrant Get User Name - -@findex getlogin_r -@cindex reentrant get user name -@cindex get user name, reentrant - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int getlogin_r( - char *name, - size_t namesize -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The arguments were invalid. - -@end table - -@subheading DESCRIPTION: - -This is a reentrant version of the @code{getlogin()} service. The -caller specified their own buffer, @code{name}, as well as the -length of this buffer, @code{namesize}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection getpgrp - Get Process Group ID - -@findex getpgrp -@cindex get process group id - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -pid_t getpgrp( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -The procress group Id is returned. - -@subheading DESCRIPTION: - -This service returns the current progress group Id. - -@subheading NOTES: - -This routine is implemented in a somewhat meaningful -way for RTEMS but is truly not functional. - -@c -@c -@c -@page -@subsection setsid - Create Session and Set Process Group ID - -@findex setsid -@cindex create session and set process group id - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -pid_t setsid( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EPERM -The application does not have permission to create a process group. - -@end table - -@subheading DESCRIPTION: - -This routine always returns @code{EPERM} as RTEMS has no way -to create new processes and thus no way to create a new process -group. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection setpgid - Set Process Group ID for Job Control - -@findex setpgid -@cindex set process group id for job control - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int setpgid( - pid_t pid, - pid_t pgid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item ENOSYS -The routine is not implemented. - -@end table - -@subheading DESCRIPTION: - -This service is not implemented for RTEMS as process groups are not -supported. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection uname - Get System Name - -@findex uname -@cindex get system name - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int uname( - struct utsname *name -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EPERM -The provided structure pointer is invalid. - -@end table - -@subheading DESCRIPTION: - -This service returns system information to the caller. It does this -by filling in the @code{struct utsname} format structure for the -caller. - -@subheading NOTES: - -The information provided includes the operating system (RTEMS in -all configurations), the node number, the release as the RTEMS -version, and the CPU family and model. The CPU model name -will indicate the multilib executive variant being used. - -@c -@c -@c -@page -@subsection times - Get process times - -@findex times -@cindex get process times - -@subheading CALLING SEQUENCE: - -@example -#include <sys/time.h> - -clock_t times( - struct tms *ptms -); -@end example - -@subheading STATUS CODES: - -This routine returns the number of clock ticks that have elapsed -since the system was initialized (e.g. the application was -started). - -@subheading DESCRIPTION: - -@code{times} stores the current process times in @code{ptms}. The -format of @code{struct tms} is as defined in -@code{<sys/times.h>}. RTEMS fills in the field @code{tms_utime} -with the number of ticks that the calling thread has executed -and the field @code{tms_stime} with the number of clock ticks -since system boot (also returned). All other fields in the -@code{ptms} are left zero. - -@subheading NOTES: - -RTEMS has no way to distinguish between user and system time -so this routine returns the most meaningful information -possible. - -@c -@c -@c -@page -@subsection getenv - Get Environment Variables - -@findex getenv -@cindex get environment variables - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -char *getenv( - const char *name -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item NULL -when no match - -@item pointer to value -when successful - -@end table - -@subheading DESCRIPTION: - -This service searches the set of environment variables for -a string that matches the specified @code{name}. If found, -it returns the associated value. - -@subheading NOTES: - -The environment list consists of name value pairs that -are of the form @i{name = value}. - -@c -@c -@c -@page -@subsection setenv - Set Environment Variables - -@findex setenv -@cindex set environment variables - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int setenv( - const char *name, - const char *value, - int overwrite -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -Returns 0 if successful and -1 otherwise. - -@subheading DESCRIPTION: - -This service adds the variable @code{name} to the environment with -@code{value}. If @code{name} is not already exist, then it is -created. If @code{name} exists and @code{overwrite} is zero, then -the previous value is not overwritten. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection ctermid - Generate Terminal Pathname - -@findex ctermid -@cindex generate terminal pathname - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -char *ctermid( - char *s -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -Returns a pointer to a string indicating the pathname for the controlling -terminal. - -@subheading DESCRIPTION: - -This service returns the name of the terminal device associated with -this process. If @code{s} is NULL, then a pointer to a static buffer -is returned. Otherwise, @code{s} is assumed to have a buffer of -sufficient size to contain the name of the controlling terminal. - -@subheading NOTES: - -By default on RTEMS systems, the controlling terminal is @code{/dev/console}. -Again this implementation is of limited meaning, but it provides -true and useful results which should be sufficient to ease porting -applications from a full POSIX implementation to the reduced -profile supported by RTEMS. - -@c -@c -@c -@page -@subsection ttyname - Determine Terminal Device Name - -@findex ttyname -@cindex determine terminal device name - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -char *ttyname( - int fd -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -Pointer to a string containing the terminal device name or -NULL is returned on any error. - -@subheading DESCRIPTION: - -This service returns a pointer to the pathname of the terminal -device that is open on the file descriptor @code{fd}. If -@code{fd} is not a valid descriptor for a terminal device, -then NULL is returned. - -@subheading NOTES: - -This routine uses a static buffer. - -@c -@c -@c -@page -@subsection ttyname_r - Reentrant Determine Terminal Device Name - -@findex ttyname_r -@cindex reentrant determine terminal device name - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int ttyname_r( - int fd, - char *name, - int namesize -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -This routine returns -1 and sets @code{errno} as follows: - -@table @b -@item EBADF -If not a valid descriptor for a terminal device. - -@item EINVAL -If @code{name} is NULL or @code{namesize} are insufficient. - -@end table - -@subheading DESCRIPTION: - -This service the pathname of the terminal device that is open -on the file descriptor @code{fd}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection isatty - Determine if File Descriptor is Terminal - -@findex isatty -@cindex determine if file descriptor is terminal - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int isatty( - int fd -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -Returns 1 if @code{fd} is a terminal device and 0 otherwise. - -@subheading DESCRIPTION: - -This service returns 1 if @code{fd} is an open file descriptor -connected to a terminal and 0 otherwise. - -@subheading NOTES: - -@c -@c -@c -@page -@subsection sysconf - Get Configurable System Variables - -@findex sysconf -@cindex get configurable system variables - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -long sysconf( - int name -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -The value returned is the actual value of the system resource. -If the requested configuration name is a feature flag, then -1 is returned if the available and 0 if it is not. On any -other error condition, -1 is returned. - -@subheading DESCRIPTION: - -This service is the mechanism by which an application determines -values for system limits or options at runtime. - -@subheading NOTES: - -Much of the information that may be obtained via @code{sysconf} -has equivalent macros in @code{<unistd.h}. However, those -macros reflect conservative limits which may have been altered -by application configuration. diff --git a/doc/posix_users/process.t b/doc/posix_users/process.t deleted file mode 100644 index 1120fb8639..0000000000 --- a/doc/posix_users/process.t +++ /dev/null @@ -1,493 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Process Creation and Execution Manager - -@section Introduction - -The process creation and execution manager provides the -functionality associated with the creation and termination -of processes. - - -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 - -POSIX process functionality can not be completely -supported by RTEMS. This is because RTEMS provides no memory -protection and implements a @i{single process, multi-threaded -execution model}. In this light, RTEMS provides none of the -routines that are associated with the creation of new processes. -However, since the entire RTEMS application (e.g. executable) -is logically a single POSIX process, RTEMS is able to provide -implementations of many operations on processes. The rule of -thumb is that those routines provide a meaningful result. -For example, @code{getpid()} returns the node number. - -@section Operations - -The only functionality method defined by this manager which is -supported by RTEMS is the @code{_exit} service. The -implementation of @code{_exit} shuts the application down and -is equivalent to invoking either @code{exit} or -@code{rtems_shutdown_executive}. - -@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. - -@c -@c -@c -@page -@subsection fork - Create a Process - -@findex fork -@cindex 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 - -@c -@c -@c -@page -@subsection execl - Execute a File - -@findex execl -@cindex 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 - -@c -@c -@c -@page -@subsection execv - Execute a File - -@findex execv -@cindex 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 - -@c -@c -@c -@page -@subsection execle - Execute a File - -@findex execle -@cindex 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 - -@c -@c -@c -@page -@subsection execve - Execute a File - -@findex execve -@cindex 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 - -@c -@c -@c -@page -@subsection execlp - Execute a File - -@findex execlp -@cindex 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 - -@c -@c -@c -@page -@subsection execvp - Execute a File - -@findex execvp -@cindex 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 - -@c -@c -@c -@page -@subsection pthread_atfork - Register Fork Handlers - -@findex pthread_atfork -@cindex 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 - -@c -@c -@c -@page -@subsection wait - Wait for Process Termination - -@findex wait -@cindex 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 - -@c -@c -@c -@page -@subsection waitpid - Wait for Process Termination - -@findex waitpid -@cindex 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 - -@c -@c -@c -@page -@subsection _exit - Terminate a Process - -@findex _exit -@cindex 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.t b/doc/posix_users/sched.t deleted file mode 100644 index 14c0185341..0000000000 --- a/doc/posix_users/sched.t +++ /dev/null @@ -1,216 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Scheduler Manager - -@section Introduction - -The scheduler manager ... - -The directives provided by the scheduler manager are: - -@itemize @bullet -@item @code{sched_get_priority_min} - Get Minimum Priority Value -@item @code{sched_get_priority_max} - Get Maximum Priority Value -@item @code{sched_rr_get_interval} - Get Timeslicing Quantum -@item @code{sched_yield} - Yield the Processor -@end itemize - -@section Background - -@subsection Priority - -In the RTEMS implementation of the POSIX API, the priorities range from -the low priority of @code{sched_get_priority_min()} to the highest priority of -@code{sched_get_priority_max()}. Numerically higher values represent higher -priorities. - -@subsection Scheduling Policies - -The following scheduling policies are available: - -@table @b -@item SCHED_FIFO -Priority-based, preemptive scheduling with no timeslicing. This is equivalent -to what is called "manual round-robin" scheduling. - -@item SCHED_RR -Priority-based, preemptive scheduling with timeslicing. Time quantums are -maintained on a per-thread basis and are not reset at each context switch. -Thus, a thread which is preempted and subsequently resumes execution will -attempt to complete the unused portion of its time quantum. - -@item SCHED_OTHER -Priority-based, preemptive scheduling with timeslicing. Time quantums are -maintained on a per-thread basis and are reset at each context switch. - -@item SCHED_SPORADIC -Priority-based, preemptive scheduling utilizing three additional parameters: -budget, replenishment period, and low priority. Under this policy, the -thread is allowed to execute for "budget" amount of time before its priority -is lowered to "low priority". At the end of each replenishment period, -the thread resumes its initial priority and has its budget replenished. - -@end table - -@section Operations - -There is currently no text in this section. - -@section Directives - -This section details the scheduler 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. - -@c -@c -@c -@page -@subsection sched_get_priority_min - Get Minimum Priority Value - -@findex sched_get_priority_min -@cindex get minimum priority value - -@subheading CALLING SEQUENCE: - -@example -#include <sched.h> - -int sched_get_priority_min( - int policy -); -@end example - -@subheading STATUS CODES: - -On error, this routine returns -1 and sets errno to one of the following: - -@table @b -@item EINVAL -The indicated policy is invalid. - -@end table - -@subheading DESCRIPTION: - -This routine return the minimum (numerically and logically lowest) priority -for the specified @code{policy}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection sched_get_priority_max - Get Maximum Priority Value - -@findex sched_get_priority_max -@cindex get maximum priority value - -@subheading CALLING SEQUENCE: - -@example -#include <sched.h> - -int sched_get_priority_max( - int policy -); -@end example - -@subheading STATUS CODES: - -On error, this routine returns -1 and sets errno to one of the following: - -@table @b -@item EINVAL -The indicated policy is invalid. - -@end table - -@subheading DESCRIPTION: - -This routine return the maximum (numerically and logically highest) priority -for the specified @code{policy}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection sched_rr_get_interval - Get Timeslicing Quantum - -@findex sched_rr_get_interval -@cindex get timeslicing quantum - -@subheading CALLING SEQUENCE: - -@example -#include <sched.h> - -int sched_rr_get_interval( - pid_t pid, - struct timespec *interval -); -@end example - -@subheading STATUS CODES: - -On error, this routine returns -1 and sets errno to one of the following: - -@table @b -@item ESRCH -The indicated process id is invalid. - -@item EINVAL -The specified interval pointer parameter is invalid. - -@end table - -@subheading DESCRIPTION: - -This routine returns the length of the timeslice quantum in the -@code{interval} parameter for the specified @code{pid}. - -@subheading NOTES: - -The @code{pid} argument should be 0 to indicate the calling process. - -@c -@c -@c -@page -@subsection sched_yield - Yield the Processor - -@findex sched_yield -@cindex yield the processor - -@subheading CALLING SEQUENCE: - -@example -#include <sched.h> - -int sched_yield( void ); -@end example - -@subheading STATUS CODES: - -This routine always returns zero to indicate success. - -@subheading DESCRIPTION: - -This call forces the calling thread to yield the processor to another -thread. Normally this is used to implement voluntary round-robin -task scheduling. - -@subheading NOTES: - -NONE diff --git a/doc/posix_users/semaphores.t b/doc/posix_users/semaphores.t deleted file mode 100644 index 71b5c38367..0000000000 --- a/doc/posix_users/semaphores.t +++ /dev/null @@ -1,595 +0,0 @@ -@c -@c COPYRIGHT(c) 1988-2002. -@c On-Line Applications Research Corporation(OAR). -@c All rights reserved. - -@chapter Semaphore Manager - -@section Introduction - -The semaphore manager provides functions to allocate, delete, and control -semaphores. This manager is based on the POSIX 1003.1 standard. - -The directives provided by the semaphore manager are: - -@itemize @bullet -@item @code{sem_init} - Initialize an unnamed semaphore -@item @code{sem_destroy} - Destroy an unnamed semaphore -@item @code{sem_open} - Open a named semaphore -@item @code{sem_close} - Close a named semaphore -@item @code{sem_unlink} - Remove a named semaphore -@item @code{sem_wait} - Lock a semaphore -@item @code{sem_trywait} - Lock a semaphore -@item @code{sem_timedwait} - Wait on a Semaphore for a Specified Time -@item @code{sem_post} - Unlock a semaphore -@item @code{sem_getvalue} - Get the value of a semeaphore -@end itemize - -@section Background - -@subsection Theory -Semaphores are used for synchronization and mutual exclusion by indicating the -availability and number of resources. The task (the task which is returning -resources) notifying other tasks of an event increases the number of resources -held by the semaphore by one. The task (the task which will obtain resources) -waiting for the event decreases the number of resources held by the semaphore -by one. If the number of resources held by a semaphore is insufficient (namely -0), the task requiring resources will wait until the next time resources are -returned to the semaphore. If there is more than one task waiting for a -semaphore, the tasks will be placed in the queue. - -@subsection "sem_t" Structure - -@findex sem_t - -The @code{sem_t} structure is used to represent semaphores. It is passed as an -argument to the semaphore directives and is defined as follows: - -@example -typedef int sem_t; -@end example - -@subsection Building a Semaphore Attribute Set - -@section Operations - -@subsection Using as a Binary Semaphore -Although POSIX supports mutexes, they are only visible between threads. To work -between processes, a binary semaphore must be used. - -Creating a semaphore with a limit on the count of 1 effectively restricts the -semaphore to being a binary semaphore. When the binary semaphore is available, -the count is 1. When the binary semaphore is unavailable, the count is 0. - -Since this does not result in a true binary semaphore, advanced binary features like the Priority Inheritance and Priority Ceiling Protocols are not available. - -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. - -@c -@c -@c -@page -@subsection sem_init - Initialize an unnamed semaphore - -@findex sem_init -@cindex initialize an unnamed semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int sem_init( - sem_t *sem, - int pshared, - unsigned int value -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The value argument exceeds SEM_VALUE_MAX - -@item ENOSPC -A resource required to initialize the semaphore has been exhausted -The limit on semaphores (SEM_VALUE_MAX) has been reached - -@item ENOSYS -The function sem_init is not supported by this implementation - -@item EPERM -The process lacks appropriate privileges to initialize the semaphore - -@end table - -@subheading DESCRIPTION: -The sem_init function is used to initialize the unnamed semaphore referred to -by "sem". The value of the initialized semaphore is the parameter "value". The -semaphore remains valid until it is destroyed. - -ADD MORE HERE XXX - -@subheading NOTES: -If the functions completes successfully, it shall return a value of zero. -Otherwise, it shall return a value of -1 and set "errno" to specify the error -that occurred. - -Multiprocessing is currently not supported in this implementation. - -@c -@c -@c -@page -@subsection sem_destroy - Destroy an unnamed semaphore - -@findex sem_destroy -@cindex destroy an unnamed semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int sem_destroy( - sem_t *sem -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The value argument exceeds SEM_VALUE_MAX - -@item ENOSYS -The function sem_init is not supported by this implementation - -@item EBUSY -There are currently processes blocked on the semaphore - -@end table - -@subheading DESCRIPTION: -The sem_destroy function is used to destroy an unnamed semaphore refered to by -"sem". sem_destroy can only be used on a semaphore that was created using -sem_init. - -@subheading NOTES: -If the functions completes successfully, it shall return a value of zero. -Otherwise, it shall return a value of -1 and set "errno" to specify the error -that occurred. - -Multiprocessing is currently not supported in this implementation. - - -@c -@c -@c -@page -@subsection sem_open - Open a named semaphore - -@findex sem_open -@cindex open a named semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int sem_open( - const char *name, - int oflag -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading ARGUMENTS: - -The following flag bit may be set in oflag: - -@code{O_CREAT} - Creates the semaphore if it does not already exist. If O_CREAT -is set and the semaphore already exists then O_CREAT has no effect. Otherwise, -sem_open() creates a semaphore. The O_CREAT flag requires the third and fourth -argument: mode and value of type mode_t and unsigned int, respectively. - -@code{O_EXCL} - If O_EXCL and O_CREAT are set, all call to sem_open() shall fail -if the semaphore name exists - -@subheading STATUS CODES: - -@table @b -@item EACCES -Valid name specified but oflag permissions are denied, or the semaphore name -specified does not exist and permission to create the named semaphore is denied. - -@item EEXIST -O_CREAT and O_EXCL are set and the named semaphore already exists. - -@item EINTR -The sem_open() operation was interrupted by a signal. - -@item EINVAL -The sem_open() operation is not supported for the given name. - -@item EMFILE -Too many semaphore descriptors or file descriptors in use by this process. - -@item ENAMETOOLONG -The length of the name exceed PATH_MAX or name component is longer than NAME_MAX -while POSIX_NO_TRUNC is in effect. - -@item ENOENT -O_CREAT is not set and the named semaphore does not exist. - -@item ENOSPC -There is insufficient space for the creation of a new named semaphore. - -@item ENOSYS -The function sem_open() is not supported by this implementation. - -@end table - -@subheading DESCRIPTION: -The sem_open() function establishes a connection between a specified semaphore and -a process. After a call to sem_open with a specified semaphore name, a process -can reference to semaphore by the associated name using the address returned by -the call. The oflag arguments listed above control the state of the semaphore by -determining if the semaphore is created or accessed by a call to sem_open(). - -@subheading NOTES: - - -@c -@c -@c -@page -@subsection sem_close - Close a named semaphore - -@findex sem_close -@cindex close a named semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int sem_close( - sem_t *sem_close -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -The semaphore argument is not a valid semaphore descriptor. - -@item ENOSYS -The function sem_close is not supported by this implementation. - -@end table - -@subheading DESCRIPTION: -The sem_close() function is used to indicate that the calling process is finished -using the named semaphore indicated by sem. The function sem_close deallocates -any system resources that were previously allocated by a sem_open system call. If -sem_close() completes successfully it returns a 1, otherwise a value of -1 is -return and errno is set. - -@subheading NOTES: - -@c -@c -@c -@page -@subsection sem_unlink - Unlink a semaphore - -@findex sem_unlink -@cindex unlink a semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int sem_unlink( - const char *name -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCESS -Permission is denied to unlink a semaphore. - -@item ENAMETOOLONG -The length of the strong name exceed NAME_MAX while POSIX_NO_TRUNC is in effect. - -@item ENOENT -The name of the semaphore does not exist. - -@item ENOSPC -There is insufficient space for the creation of a new named semaphore. - -@item ENOSYS -The function sem_unlink is not supported by this implementation. - -@end table - -@subheading DESCRIPTION: -The sem_unlink() function shall remove the semaphore name by the string name. If -a process is currently accessing the name semaphore, the sem_unlink command has -no effect. If one or more processes have the semaphore open when the sem_unlink -function is called, the destruction of semaphores shall be postponed until all -reference to semaphore are destroyed by calls to sem_close, _exit(), or exec. -After all references have been destroyed, it returns immediately. - -If the termination is successful, the function shall return 0. Otherwise, a -1 -is returned and the errno is set. - -@subheading NOTES: - -@c -@c -@c -@page -@subsection sem_wait - Wait on a Semaphore - -@findex sem_wait -@cindex wait on a semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int sem_wait( - sem_t *sem -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The "sem" argument does not refer to a valid semaphore - -@end table - -@subheading DESCRIPTION: -This function attempts to lock a semaphore specified by @code{sem}. If the -semaphore is available, then the semaphore is locked (i.e., the semaphore -value is decremented). If the semaphore is unavailable (i.e., the semaphore -value is zero), then the function will block until the semaphore becomes -available. It will then successfully lock the semaphore. The semaphore -remains locked until released by a @code{sem_post()} call. - -If the call is unsuccessful, then the function returns -1 and sets errno to the -appropriate error code. - -@subheading NOTES: -Multiprocessing is not supported in this implementation. - -@c -@c -@c -@page -@subsection sem_trywait - Non-blocking Wait on a Semaphore - -@findex sem_trywait -@cindex non - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int sem_trywait( - sem_t *sem -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EAGAIN -The semaphore is not available (i.e., the semaphore value is zero), so the -semaphore could not be locked. - -@item EINVAL -The @code{sem} argument does not refewr to a valid semaphore - -@end table - -@subheading DESCRIPTION: -This function attempts to lock a semaphore specified by @code{sem}. If the -semaphore is available, then the semaphore is locked (i.e., the semaphore -value is decremented) and the function returns a value of 0. The semaphore -remains locked until released by a @code{sem_post()} call. If the semaphore -is unavailable (i.e., the semaphore value is zero), then the function will -return a value of -1 immediately and set @code{errno} to EAGAIN. - -If the call is unsuccessful, then the function returns -1 and sets -@code{errno} to the appropriate error code. - -@subheading NOTES: -Multiprocessing is not supported in this implementation. - -@c -@c -@c -@page -@subsection sem_timedwait - Wait on a Semaphore for a Specified Time - -@findex sem_timedwait -@cindex wait on a semaphore for a specified time - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int sem_timedwait( - sem_t *sem, - const struct timespec *abstime -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EAGAIN -The semaphore is not available (i.e., the semaphore value is zero), so the -semaphore could not be locked. - -@item EINVAL -The @code{sem} argument does not refewr to a valid semaphore - -@end table - -@subheading DESCRIPTION: - -This function attemtps to lock a semaphore specified by @code{sem}, -and will wait for the semaphore until the absolute time specified by -@code{abstime}. If the semaphore is available, then the semaphore is -locked (i.e., the semaphore value is decremented) and the function -returns a value of 0. The semaphore remains locked until released by -a @code{sem_post()} call. If the semaphore is unavailable, then the -function will wait for the semaphore to become available for the amount -of time specified by @code{timeout}. - -If the semaphore does not become available within the interval specified by -@code{timeout}, then the function returns -1 and sets @code{errno} to EAGAIN. -If any other error occurs, the function returns -1 and sets @code{errno} to -the appropriate error code. - -@subheading NOTES: -Multiprocessing is not supported in this implementation. - -@c -@c -@c -@page -@subsection sem_post - Unlock a Semaphore - -@findex sem_post -@cindex unlock a semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int sem_post( - sem_t *sem -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The @code{sem} argument does not refer to a valid semaphore - -@end table - -@subheading DESCRIPTION: -This function attempts to release the semaphore specified by @code{sem}. If -other tasks are waiting on the semaphore, then one of those tasks (which one -depends on the scheduler being used) is allowed to lock the semaphore and -return from its @code{sem_wait()}, @code{sem_trywait()}, or -@code{sem_timedwait()} call. If there are no other tasks waiting on the -semaphore, then the semaphore value is simply incremented. @code{sem_post()} -returns 0 upon successful completion. - -If an error occurs, the function returns -1 and sets @code{errno} to the -appropriate error code. - -@subheading NOTES: -Multiprocessing is not supported in this implementation. - -@c -@c -@c -@page -@subsection sem_getvalue - Get the value of a semaphore - -@findex sem_getvalue -@cindex get the value of a semaphore - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -int sem_getvalue( - sem_t *sem, - int *sval -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The "sem" argument does not refer to a valid semaphore - -@item ENOSYS -The function sem_getvalue is not supported by this implementation - -@end table - -@subheading DESCRIPTION: -The sem_getvalue functions sets the location referenced by the "sval" argument -to the value of the semaphore without affecting the state of the semaphore. The -updated value represents a semaphore value that occurred at some point during -the call, but is not necessarily the actual value of the semaphore when it -returns to the calling process. - -If "sem" is locked, the value returned by sem_getvalue will be zero or a -negative number whose absolute value is the number of processes waiting for the -semaphore at some point during the call. - -@subheading NOTES: -If the functions completes successfully, it shall return a value of zero. -Otherwise, it shall return a value of -1 and set "errno" to specify the error -that occurred. diff --git a/doc/posix_users/signal.t b/doc/posix_users/signal.t deleted file mode 100644 index 1b7dc554c0..0000000000 --- a/doc/posix_users/signal.t +++ /dev/null @@ -1,1071 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Signal Manager - -@section Introduction - -The signal manager provides the functionality associated with -the generation, delivery, and management of process-oriented -signals. - -The directives provided by the signal manager are: - -@itemize @bullet -@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 -@item @code{ualarm} - Schedule Alarm in Microseconds -@end itemize - -@section Background - -@subsection Signals - -POSIX signals are an asynchronous event mechanism. Each process -and thread has a set of signals associated with it. Individual -signals may be enabled (e.g. unmasked) or blocked (e.g. ignored) -on both a per-thread and process level. Signals which are -enabled have a signal handler associated with them. When the -signal is generated and conditions are met, then the signal -handler is invoked in the proper process or thread context -asynchronous relative to the logical thread of execution. - -If a signal has been blocked when it is generated, then it -is queued and kept pending until the thread or process unblocks -the signal or explicitly checks for it. -Traditional, non-real-time POSIX signals do not queue. Thus -if a process or thread has blocked a particular signal, then -multiple occurrences of that signal are recorded as a -single occurrence of that signal. -@c TODO: SIGRTMIN and SIGRTMAX ? - -One can check for the set of outstanding signals that have been -blocked. Services are provided to check for outstanding process -or thread directed signals. - -@subsection Signal Delivery - -Signals which are directed at a thread are delivered to the specified thread. - -Signals which are 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 @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 -(@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 -the signal is delivered to the highest priority thread of this set. In the -event, multiple threads of the same priority are willing to accept this -signal, then priority is given first to ready threads, then to threads -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 (@code{sigprocmask()} or -@code{pthread_sigprocmask()}) or to wait for this signal -(@code{sigwait()}) will be the recipient of the signal. - -@end enumerate - -@section Operations - -@subsection Signal Set Management - -Each process and each thread within that process has a set of -individual signals and handlers associated with it. Services -are provided to construct signal sets for the purposes of building -signal sets -- type @code{sigset_t} -- that are used to -provide arguments to the services that mask, unmask, and -check on pending signals. - -@subsection Blocking Until Signal Generation - -A thread may block until receipt of a signal. The "sigwait" -and "pause" families of functions block until the requested -signal is received or if using @code{sigtimedwait()} until the specified -timeout period has elapsed. - -@subsection Sending a Signal - -This is accomplished -via one of a number of services that sends a signal to either a -process or thread. Signals may be directed at a process by -the service @code{kill()} or at a thread by the service -@code{pthread_kill()} - -@section Directives - -This section details the signal 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. - -@c -@c -@c -@page -@subsection sigaddset - Add a Signal to a Signal Set - -@findex sigaddset -@cindex add a signal to a signal set - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigaddset( - sigset_t *set, - int signo -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b -@item EINVAL -Invalid argument passed. - -@end table - -@subheading DESCRIPTION: - -This function adds the signal @code{signo} to the specified signal @code{set}. - -@subheading NOTES: - -The set must be initialized using either @code{sigemptyset} or @code{sigfillset} -before using this function. - -@c -@c -@c -@page -@subsection sigdelset - Delete a Signal from a Signal Set - -@findex sigdelset -@cindex delete a signal from a signal set - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigdelset( - sigset_t *set, - int signo -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b -@item EINVAL -Invalid argument passed. - -@end table - -@subheading DESCRIPTION: - -This function deletes the signal specified by @code{signo} from the specified -signal @code{set}. - -@subheading NOTES: - -The set must be initialized using either @code{sigemptyset} or @code{sigfillset} -before using this function. - -@c -@c -@c -@page -@subsection sigfillset - Fill a Signal Set - -@findex sigfillset -@cindex fill a signal set - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigfillset( - sigset_t *set -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b -@item EINVAL -Invalid argument passed. - -@end table - -@subheading DESCRIPTION: - -This function fills the specified signal @code{set} such that all -signals are set. - -@c -@c -@c -@page -@subsection sigismember - Is Signal a Member of a Signal Set - -@findex sigismember -@cindex is signal a member of a signal set - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigismember( - const sigset_t *set, - int signo -); -@end example - -@subheading STATUS CODES: - -The function returns either 1 or 0 if completed successfully, otherwise it -returns -1 and sets @code{errno} to indicate the error. @code{errno} may be set -to: - -@table @b - -@item EINVAL -Invalid argument passed. - -@end table - -@subheading DESCRIPTION: - -This function returns returns 1 if @code{signo} is a member of @code{set} -and 0 otherwise. - -@subheading NOTES: - -The set must be initialized using either @code{sigemptyset} or @code{sigfillset} -before using this function. - -@c -@c -@c -@page -@subsection sigemptyset - Empty a Signal Set - -@findex sigemptyset -@cindex empty a signal set - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigemptyset( - sigset_t *set -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b -@item EINVAL -Invalid argument passed. - -@end table - -@subheading DESCRIPTION: - -This function initializes an empty signal set pointed to by @code{set}. - -@c -@c -@c -@page -@subsection sigaction - Examine and Change Signal Action - -@findex sigaction -@cindex examine and change signal action - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigaction( - int sig, - const struct sigaction *act, - struct sigaction *oact -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b -@item EINVAL -Invalid argument passed. - -@item ENOTSUP -Realtime Signals Extension option not supported. - -@end table - -@subheading DESCRIPTION: - -If the argument act is not a null pointer, it points to a structure specifying -the action to be associated with the specified signal. If the argument oact is -not a null pointer, the action previously associated with the signal is stored -in the location pointed to by the argument oact. If the argument act is a null -pointer, signal handling is unchanged; thus, the call can be used to enquire -about the current handling of a given signal. - -The structure @code{sigaction} has the following members: - -@table @code - -@item void(*)(int) sa_handler -Pointer to a signal-catching function or one of the macros SIG_IGN or SIG_DFL. - -@item sigset_t sa_mask -Additional set of signals to be blocked during execution of signal-catching function. - -@item int sa_flags -Special flags to affect behavior of signal. - -@item void(*)(int, siginfo_t*, void*) sa_sigaction -Alternative pointer to a signal-catching function. - -@end table - -@code{sa_handler} and @code{sa_sigaction} should never be used at the same time as their storage may overlap. - -If the @code{SA_SIGINFO} flag (see below) is set in @code{sa_flags}, the -@code{sa_sigaction} field specifies a signal-catching function, otherwise -@code{sa_handler} specifies the action to be associated with the signal, which -may be a signal-catching function or one of the macros @code{SIG_IGN} or -@code{SIG_DFN}. - -The following flags can be set in the @code{sa_flags} field: - -@table @code - -@c I found no evidence that other flags are used in the source code. -@c I did a fulltext search in cpukit/posix/, maybe I looked in the wrong place? -@item SA_SIGINFO -If not set, the signal-catching function should be declared as @code{void -func(int signo)} and the address of the function should be set in -@code{sa_handler}. If set, the signal-catching function should be declared as -@code{void func(int signo, siginfo_t* info, void* context)} and the address of -the function should be set in @code{sa_sigaction}. - -@end table - -The prototype of the @code{siginfo_t} structure is the following: -@example -typedef struct -@{ - int si_signo; /* Signal number */ - int si_code; /* Cause of the signal */ - pid_t si_pid; /* Sending process ID */ - uid_t si_uid; /* Real user ID of sending process */ - void* si_addr; /* Address of faulting instruction */ - int si_status; /* Exit value or signal */ - union sigval - @{ - int sival_int; /* Integer signal value */ - void* sival_ptr; /* Pointer signal value */ - @} si_value; /* Signal value */ -@} -@end example - -@subheading NOTES: - -The signal number cannot be SIGKILL. - -@c -@c -@c -@page -@subsection pthread_kill - Send a Signal to a Thread - -@findex pthread_kill -@cindex send a signal to a thread - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int pthread_kill( - pthread_t thread, - int sig -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b - -@item ESRCH -The thread indicated by the parameter thread is invalid. - -@item EINVAL -Invalid argument passed. - -@end table - -@subheading DESCRIPTION: - -This functions sends the specified signal @code{sig} to a thread referenced -to by @code{thread}. - -If the signal code is @code{0}, arguments are validated and no signal is sent. - - -@c -@c -@c -@page -@subsection sigprocmask - Examine and Change Process Blocked Signals - -@findex sigprocmask -@cindex examine and change process blocked signals - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigprocmask( - int how, - const sigset_t *set, - sigset_t *oset -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b - -@item EINVAL -Invalid argument passed. - -@end table - -@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}. If @code{set} is @b{NULL}, no change is -done, allowing to examine the set of currently blocked signals. - -@subheading NOTES: - -It is not an error to unblock a signal which is not blocked. - -In the current implementation of RTEMS POSIX API sigprocmask() is technically -mapped to pthread_sigmask(). - -@c -@c -@c -@page -@subsection pthread_sigmask - Examine and Change Thread Blocked Signals - -@findex pthread_sigmask -@cindex examine and change thread blocked signals - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int pthread_sigmask( - int how, - const sigset_t *set, - sigset_t *oset -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b - -@item EINVAL -Invalid argument passed. - -@end table - -@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}. If @code{set} is @b{NULL}, no change is -done, allowing to examine the set of currently blocked signals. - -@subheading NOTES: - -It is not an error to unblock a signal which is not blocked. - - -@c -@c -@c -@page -@subsection kill - Send a Signal to a Process - -@findex kill -@cindex send a signal to a process - -@subheading CALLING SEQUENCE: - -@example -#include <sys/types.h> -#include <signal.h> - -int kill( - pid_t pid, - int sig -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b -@item EINVAL -Invalid argument passed. - -@item EPERM -Process does not have permission to send the signal to any receiving process. - -@item ESRCH -The process indicated by the parameter pid is invalid. - -@end table - -@subheading DESCRIPTION: - -This function sends the signal @code{sig} to the process @code{pid}. - -@subheading NOTES: - -Since RTEMS is a single-process system, a signal can only be sent to the calling -process (i.e. the current node). - -@c -@c -@c -@page -@subsection sigpending - Examine Pending Signals - -@findex sigpending -@cindex examine pending signals - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigpending( - const sigset_t *set -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@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}. - -@c -@c -@c -@page -@subsection sigsuspend - Wait for a Signal - -@findex sigsuspend -@cindex wait for a signal - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigsuspend( - const sigset_t *sigmask -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b - -@item EINTR -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 a signal is raised. - -@c -@c -@c -@page -@subsection pause - Suspend Process Execution - -@findex pause -@cindex suspend process execution - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int pause( void ); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b - -@item EINTR -Signal interrupted this function. - -@end table - -@subheading DESCRIPTION: - -This function causes the calling thread to be blocked until an -unblocked signal is received. - -@c -@c -@c -@page -@subsection sigwait - Synchronously Accept a Signal - -@findex sigwait -@cindex synchronously accept a signal - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigwait( - const sigset_t *set, - int *sig -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b - -@item EINVAL -Invalid argument passed. - -@item EINTR -Signal interrupted this function. - -@end table - -@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}. - -@c -@c -@c -@page -@subsection sigwaitinfo - Synchronously Accept a Signal - -@findex sigwaitinfo -@cindex synchronously accept a signal - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigwaitinfo( - const sigset_t *set, - siginfo_t *info -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b - -@item EINTR -Signal interrupted this function. - -@end table - -@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 prototype of the @code{siginfo_t} structure is the following: -@example -typedef struct -@{ - int si_signo; /* Signal number */ - int si_code; /* Cause of the signal */ - pid_t si_pid; /* Sending process ID */ - uid_t si_uid; /* Real user ID of sending process */ - void* si_addr; /* Address of faulting instruction */ - int si_status; /* Exit value or signal */ - union sigval - @{ - int sival_int; /* Integer signal value */ - void* sival_ptr; /* Pointer signal value */ - @} si_value; /* Signal value */ -@} -@end example - -@c -@c -@c -@page -@subsection sigtimedwait - Synchronously Accept a Signal with Timeout - -@findex sigtimedwait -@cindex synchronously accept a signal with timeout - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigtimedwait( - const sigset_t *set, - siginfo_t *info, - const struct timespec *timeout -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b - -@item EAGAIN -Timed out while waiting for the specified signal set. - -@item EINVAL -Nanoseconds field of the timeout argument is invalid. - -@item EINTR -Signal interrupted this function. - -@end table - -@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. - -The @code{timespec} structure is defined as follows: -@example -struct timespec -@{ - time_t tv_sec; /* Seconds */ - long tv_nsec; /* Nanoseconds */ -@} -@end example - -@subheading NOTES: - -If @code{timeout} is NULL, then the calling thread will wait forever for -the specified signal set. - -@c -@c -@c -@page -@subsection sigqueue - Queue a Signal to a Process - -@findex sigqueue -@cindex queue a signal to a process - -@subheading CALLING SEQUENCE: - -@example -#include <signal.h> - -int sigqueue( - pid_t pid, - int signo, - const union sigval value -); -@end example - -@subheading STATUS CODES: - -The function returns 0 on success, otherwise it returns -1 and sets -@code{errno} to indicate the error. @code{errno} may be set to: - -@table @b - -@item EAGAIN -No resources available to queue the signal. The process has already -queued SIGQUEUE_MAX signals that are still pending at the receiver -or the systemwide resource limit has been exceeded. - -@item EINVAL -The value of the signo argument is an invalid or unsupported signal -number. - -@item EPERM -The process does not have the appropriate privilege to send the signal -to the receiving process. - -@item ESRCH -The process pid does not exist. - -@end table - -@subheading DESCRIPTION: - -This function sends the signal specified by @code{signo} to the -process @code{pid} - -The @code{sigval} union is specified as: -@example -union sigval -@{ - int sival_int; /* Integer signal value */ - void* sival_ptr; /* Pointer signal value */ -@} -@end example - -@subheading NOTES: - -Since RTEMS is a single-process system, a signal can only be sent to the calling -process (i.e. the current node). - -@c -@c -@c -@page -@subsection alarm - Schedule Alarm - -@findex alarm -@cindex schedule alarm - -@subheading CALLING SEQUENCE: - -@example -#include <unistd.h> - -unsigned int alarm( - unsigned int seconds -); -@end example - -@subheading STATUS CODES: - -This call always succeeds. - -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 DESCRIPTION: - -The @code{alarm()} service causes the @code{SIGALRM} signal to -be generated after the number of seconds specified by -@code{seconds} has elapsed. - -@subheading NOTES: - -Alarm requests do not queue. If @code{alarm} is called while -a previous request is outstanding, the call will result in -rescheduling the time at which the @code{SIGALRM} signal -will be generated. - -If the notification signal, @code{SIGALRM}, is not caught or ignored, the -calling process is terminated. - -@c -@c -@c -@page -@subsection ualarm - Schedule Alarm in Microseconds - -@findex alarm -@findex microseonds alarm -@findex usecs alarm -@cindex schedule alarm in microseonds - -@subheading CALLING SEQUENCE: - -@example -#include <unistd.h> - -useconds_t ualarm( - useconds_t useconds, - useconds_t interval -); -@end example - -@subheading STATUS CODES: - -This call always succeeds. - -If there was a previous @code{ualarm()} 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 DESCRIPTION: - -The @code{ualarm()} service causes the @code{SIGALRM} signal to -be generated after the number of microseconds specified by -@code{useconds} has elapsed. - -When @code{interval} is non-zero, repeated timeout notification occurs -with a period in microseconds specified by @code{interval}. - -@subheading NOTES: - -Alarm requests do not queue. If @code{alarm} is called while -a previous request is outstanding, the call will result in -rescheduling the time at which the @code{SIGALRM} signal -will be generated. - -If the notification signal, @code{SIGALRM}, is not caught or ignored, the -calling process is terminated. - diff --git a/doc/posix_users/stamp-vti b/doc/posix_users/stamp-vti deleted file mode 100644 index 5634951ec8..0000000000 --- a/doc/posix_users/stamp-vti +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 24 February 2013 -@set UPDATED-MONTH February 2013 -@set EDITION 4.10.99.0 -@set VERSION 4.10.99.0 diff --git a/doc/posix_users/status.t b/doc/posix_users/status.t deleted file mode 100644 index d67fa2e019..0000000000 --- a/doc/posix_users/status.t +++ /dev/null @@ -1,58 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Status of Implementation - -This chapter provides an overview of the status of the implementation -of the POSIX API for RTEMS. The @i{POSIX 1003.1b Compliance Guide} -provides more detailed information regarding the implementation of -each of the numerous functions, constants, and macros specified by -the POSIX 1003.1b standard. - -RTEMS supports many of the process and user/group oriented services -in a "single user/single process" manner. This means that although -these services may be of limited usefulness or functionality, they -are provided and do work in a coherent manner. This is significant -when porting existing code from UNIX to RTEMS. - -@itemize @bullet -@item Implementation -@itemize @bullet -@item The current implementation of @code{dup()} is insufficient. -@item FIFOs @code{mkfifo()} are not currently implemented. -@item Asynchronous IO is not implemented. -@item The @code{flockfile()} family is not implemented -@item getc/putc unlocked family is not implemented -@item Shared Memory is not implemented -@item Mapped Memory is not implemented -@item NOTES: -@itemize @bullet -@item For Shared Memory and Mapped Memory services, it is unclear what -level of support is appropriate and possible for RTEMS. -@end itemize -@end itemize - - -@item Functional Testing -@itemize @bullet -@item Tests for unimplemented services -@end itemize - -@item Performance Testing -@itemize @bullet -@item There are no POSIX Performance Tests. -@end itemize - -@item Documentation -@itemize @bullet -@item Many of the service description pages are not complete in this -manual. These need to be completed and information added to the -background and operations sections. -@item Example programs (not just tests) would be very nice. -@end itemize - -@end itemize - - diff --git a/doc/posix_users/systemdb.t b/doc/posix_users/systemdb.t deleted file mode 100644 index d6ffc43765..0000000000 --- a/doc/posix_users/systemdb.t +++ /dev/null @@ -1,304 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2002. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@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} - Get Group File Entry for ID -@item @code{getgrgid_r} - Reentrant Get Group File Entry -@item @code{getgrnam} - Get Group File Entry for Name -@item @code{getgrnam_r} - Reentrant Get Group File Entry for Name -@item @code{getpwuid} - Get Password File Entry for UID -@item @code{getpwuid_r} - Reentrant Get Password File Entry for UID -@item @code{getpwnam} - Get Password File Entry for Name -@item @code{getpwnam_r} - Reentrant Get Password File Entry for Name -@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. - -@c -@c -@c -@page -@subsection getgrgid - Get Group File Entry for ID - -@findex getgrgid -@cindex get group file entry for id - -@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: - -@c -@c -@c -@page -@subsection getgrgid_r - Reentrant Get Group File Entry - -@findex getgrgid_r -@cindex reentrant get group file entry - -@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: - -@c -@c -@c -@page -@subsection getgrnam - Get Group File Entry for Name - -@findex getgrnam -@cindex get group file entry for name - -@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: - -@c -@c -@c -@page -@subsection getgrnam_r - Reentrant Get Group File Entry for Name - -@findex getgrnam_r -@cindex reentrant get group file entry for name - -@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: - -@c -@c -@c -@page -@subsection getpwuid - Get Password File Entry for UID - -@findex getpwuid -@cindex get password file entry for uid - -@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: - -@c -@c -@c -@page -@subsection getpwuid_r - Reentrant Get Password File Entry for UID - -@findex getpwuid_r -@cindex reentrant get password file entry for uid - -@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: - -@c -@c -@c -@page -@subsection getpwnam - Password File Entry for Name - -@findex getpwnam -@cindex password file entry for name - -@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: - -@c -@c -@c -@page -@subsection getpwnam_r - Reentrant Get Password File Entry for Name - -@findex getpwnam_r -@cindex reentrant get password file entry for name - -@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.t b/doc/posix_users/thread.t deleted file mode 100644 index c630e03d6e..0000000000 --- a/doc/posix_users/thread.t +++ /dev/null @@ -1,1577 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-2014. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. - -@chapter Thread Manager - -@section Introduction - -The thread manager implements the functionality required of the thread -manager as defined by POSIX 1003.1b. This standard requires that -a compliant operating system provide the facilties to manage multiple -threads of control and defines the API that must be provided. - -The services provided by the thread manager are: - -@itemize @bullet -@item @code{pthread_attr_init} - Initialize a Thread Attribute Set -@item @code{pthread_attr_destroy} - Destroy a Thread Attribute Set -@item @code{pthread_attr_setdetachstate} - Set Detach State -@item @code{pthread_attr_getdetachstate} - Get Detach State -@item @code{pthread_attr_setstacksize} - Set Thread Stack Size -@item @code{pthread_attr_getstacksize} - Get Thread Stack Size -@item @code{pthread_attr_setstackaddr} - Set Thread Stack Address -@item @code{pthread_attr_getstackaddr} - Get Thread Stack Address -@item @code{pthread_attr_setscope} - Set Thread Scheduling Scope -@item @code{pthread_attr_getscope} - Get Thread Scheduling Scope -@item @code{pthread_attr_setinheritsched} - Set Inherit Scheduler Flag -@item @code{pthread_attr_getinheritsched} - Get Inherit Scheduler Flag -@item @code{pthread_attr_setschedpolicy} - Set Scheduling Policy -@item @code{pthread_attr_getschedpolicy} - Get Scheduling Policy -@item @code{pthread_attr_setschedparam} - Set Scheduling Parameters -@item @code{pthread_attr_getschedparam} - Get Scheduling Parameters -@item @code{pthread_attr_getaffinity_np} - Get Thread Affinity Attribute -@item @code{pthread_attr_setaffinity_np} - Set Thread Affinity Attribute -@item @code{pthread_create} - Create a Thread -@item @code{pthread_exit} - Terminate the Current Thread -@item @code{pthread_detach} - Detach a Thread -@item @code{pthread_getattr_np} - Get Thread Attributes -@item @code{pthread_join} - Wait for Thread Termination -@item @code{pthread_self} - Get Thread ID -@item @code{pthread_equal} - Compare Thread IDs -@item @code{pthread_once} - Dynamic Package Initialization -@item @code{pthread_setschedparam} - Set Thread Scheduling Parameters -@item @code{pthread_getschedparam} - Get Thread Scheduling Parameters -@item @code{pthread_getaffinity_np} - Get Thread Affinity -@item @code{pthread_setaffinity_np} - Set Thread Affinity -@end itemize - -@section Background - -@subsection Thread Attributes - -Thread attributes are utilized only at thread creation time. A thread -attribute structure may be initialized and passed as an argument to -the @code{pthread_create} routine. - -@table @b -@item stack address -is the address of the optionally user specified stack area for this thread. -If this value is NULL, then RTEMS allocates the memory for the thread stack -from the RTEMS Workspace Area. Otherwise, this is the user specified -address for the memory to be used for the thread's stack. Each thread must -have a distinct stack area. Each processor family has different alignment -rules which should be followed. - -@item stack size -is the minimum desired size for this thread's stack area. -If the size of this area as specified by the stack size attribute -is smaller than the minimum for this processor family and the stack -is not user specified, then RTEMS will automatically allocate a -stack of the minimum size for this processor family. - -@item contention scope -specifies the scheduling contention scope. RTEMS only supports the -PTHREAD_SCOPE_PROCESS scheduling contention scope. - -@item scheduling inheritance -specifies whether a user specified or the scheduling policy and -parameters of the currently executing thread are to be used. When -this is PTHREAD_INHERIT_SCHED, then the scheduling policy and -parameters of the currently executing thread are inherited by -the newly created thread. - -@item scheduling policy and parameters -specify the manner in which the thread will contend for the processor. -The scheduling parameters are interpreted based on the specified policy. -All policies utilize the thread priority parameter. - -@end table - -@section Operations - -There is currently no text in this section. - -@section Services - -This section details the thread manager's services. -A subsection is dedicated to each of this manager's services -and describes the calling sequence, related constants, usage, -and status codes. - -@c -@c -@c -@page -@subsection pthread_attr_init - Initialize a Thread Attribute Set - -@findex pthread_attr_init -@cindex initialize a thread attribute set - -@subheading CALLING SEQUENCE: - - -@example -#include <pthread.h> - -int pthread_attr_init( - pthread_attr_t *attr -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_init} routine initializes the thread attributes -object specified by @code{attr} with the default value for all of the -individual attributes. - -@subheading NOTES: - -The settings in the default attributes are implementation defined. For -RTEMS, the default attributes are as follows: - -@itemize @bullet - -@item stackadr -is not set to indicate that RTEMS is to allocate the stack memory. - -@item stacksize -is set to @code{PTHREAD_MINIMUM_STACK_SIZE}. - -@item contentionscope -is set to @code{PTHREAD_SCOPE_PROCESS}. - -@item inheritsched -is set to @code{PTHREAD_INHERIT_SCHED} to indicate that the created -thread inherits its scheduling attributes from its parent. - -@item detachstate -is set to @code{PTHREAD_CREATE_JOINABLE}. - -@end itemize - - -@c -@c -@c -@page -@subsection pthread_attr_destroy - Destroy a Thread Attribute Set - -@findex pthread_attr_destroy -@cindex destroy a thread attribute set - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_destroy( - pthread_attr_t *attr -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_destroy} routine is used to destroy a thread -attributes object. The behavior of using an attributes object after -it is destroyed is implementation dependent. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection pthread_attr_setdetachstate - Set Detach State - -@findex pthread_attr_setdetachstate -@cindex set detach state - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_setdetachstate( - pthread_attr_t *attr, - int detachstate -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The detachstate argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_setdetachstate} routine is used to value of the -@code{detachstate} attribute. This attribute controls whether the -thread is created in a detached state. - -The @code{detachstate} can be either @code{PTHREAD_CREATE_DETACHED} or -@code{PTHREAD_CREATE_JOINABLE}. The default value for all threads is -@code{PTHREAD_CREATE_JOINABLE}. - -@subheading NOTES: - -If a thread is in a detached state, -then the use of the ID with the @code{pthread_detach} or -@code{pthread_join} routines is an error. - -@c -@c -@c -@page -@subsection pthread_attr_getdetachstate - Get Detach State - -@findex pthread_attr_getdetachstate -@cindex get detach state - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_getdetachstate( - const pthread_attr_t *attr, - int *detachstate -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The detatchstate pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_getdetachstate} routine is used to obtain the -current value of the @code{detachstate} attribute as specified -by the @code{attr} thread attribute object. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection pthread_attr_setstacksize - Set Thread Stack Size - -@findex pthread_attr_setstacksize -@cindex set thread stack size - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_setstacksize( - pthread_attr_t *attr, - size_t stacksize -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_setstacksize} routine is used to set the -@code{stacksize} attribute in the @code{attr} thread attribute -object. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_ATTR_STACKSIZE} to indicate that this -routine is supported. - -If the specified stacksize is below the minimum required for this CPU -(@code{PTHREAD_STACK_MIN}, then the stacksize will be set to the minimum -for this CPU. - -@c -@c -@c -@page -@subsection pthread_attr_getstacksize - Get Thread Stack Size - -@findex pthread_attr_getstacksize -@cindex get thread stack size - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_getstacksize( - const pthread_attr_t *attr, - size_t *stacksize -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The stacksize pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_getstacksize} routine is used to obtain the -@code{stacksize} attribute in the @code{attr} thread attribute -object. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_ATTR_STACKSIZE} to indicate that this -routine is supported. - -@c -@c -@c -@page -@subsection pthread_attr_setstackaddr - Set Thread Stack Address - -@findex pthread_attr_setstackaddr -@cindex set thread stack address - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_setstackaddr( - pthread_attr_t *attr, - void *stackaddr -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_setstackaddr} routine is used to set the -@code{stackaddr} attribute in the @code{attr} thread attribute -object. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_ATTR_STACKADDR} to indicate that this -routine is supported. - -It is imperative to the proper operation of the system that -each thread have sufficient stack space. - -@c -@c -@c -@page -@subsection pthread_attr_getstackaddr - Get Thread Stack Address - -@findex pthread_attr_getstackaddr -@cindex get thread stack address - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_getstackaddr( - const pthread_attr_t *attr, - void **stackaddr -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The stackaddr pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_getstackaddr} routine is used to obtain the -@code{stackaddr} attribute in the @code{attr} thread attribute -object. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_ATTR_STACKADDR} to indicate that this -routine is supported. - -@c -@c -@c -@page -@subsection pthread_attr_setscope - Set Thread Scheduling Scope - -@findex pthread_attr_setscope -@cindex set thread scheduling scope - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_setscope( - pthread_attr_t *attr, - int contentionscope -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The contention scope specified is not valid. - -@item ENOTSUP -The contention scope specified (PTHREAD_SCOPE_SYSTEM) is not supported. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_setscope} routine is used to set the contention -scope field in the thread attribute object @code{attr} to the value -specified by @code{contentionscope}. - -The @code{contentionscope} must be either @code{PTHREAD_SCOPE_SYSTEM} -to indicate that the thread is to be within system scheduling contention -or @code{PTHREAD_SCOPE_PROCESS} indicating that the thread is to be -within the process scheduling contention scope. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the -family of routines to which this routine belongs is supported. - -@c -@c -@c -@page -@subsection pthread_attr_getscope - Get Thread Scheduling Scope - -@findex pthread_attr_getscope -@cindex get thread scheduling scope - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_getscope( - const pthread_attr_t *attr, - int *contentionscope -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The contentionscope pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_getscope} routine is used to obtain the -value of the contention scope field in the thread attributes -object @code{attr}. The current value is returned in -@code{contentionscope}. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the -family of routines to which this routine belongs is supported. -@c -@c -@c -@page -@subsection pthread_attr_setinheritsched - Set Inherit Scheduler Flag - -@findex pthread_attr_setinheritsched -@cindex set inherit scheduler flag - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_setinheritsched( - pthread_attr_t *attr, - int inheritsched -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The specified scheduler inheritance argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_setinheritsched} routine is used to set the -inherit scheduler field in the thread attribute object @code{attr} to -the value specified by @code{inheritsched}. - -The @code{contentionscope} must be either @code{PTHREAD_INHERIT_SCHED} -to indicate that the thread is to inherit the scheduling policy -and parameters fromthe creating thread, or @code{PTHREAD_EXPLICIT_SCHED} -to indicate that the scheduling policy and parameters for this thread -are to be set from the corresponding values in the attributes object. -If @code{contentionscope} is @code{PTHREAD_INHERIT_SCHED}, then the -scheduling attributes in the @code{attr} structure will be ignored -at thread creation time. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the -family of routines to which this routine belongs is supported. - -@c -@c -@c -@page -@subsection pthread_attr_getinheritsched - Get Inherit Scheduler Flag - -@findex pthread_attr_getinheritsched -@cindex get inherit scheduler flag - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_getinheritsched( - const pthread_attr_t *attr, - int *inheritsched -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The inheritsched pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_getinheritsched} routine is used to -object the current value of the inherit scheduler field in -the thread attribute object @code{attr}. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the -family of routines to which this routine belongs is supported. - -@c -@c -@c -@page -@subsection pthread_attr_setschedpolicy - Set Scheduling Policy - -@findex pthread_attr_setschedpolicy -@cindex set scheduling policy - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_setschedpolicy( - pthread_attr_t *attr, - int policy -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item ENOTSUP -The specified scheduler policy argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_setschedpolicy} routine is used to set the -scheduler policy field in the thread attribute object @code{attr} to -the value specified by @code{policy}. - -Scheduling policies may be one of the following: - -@itemize @bullet - -@item @code{SCHED_DEFAULT} -@item @code{SCHED_FIFO} -@item @code{SCHED_RR} -@item @code{SCHED_SPORADIC} -@item @code{SCHED_OTHER} - -@end itemize - -The precise meaning of each of these is discussed elsewhere in this -manual. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the -family of routines to which this routine belongs is supported. - -@c -@c -@c -@page -@subsection pthread_attr_getschedpolicy - Get Scheduling Policy - -@findex pthread_attr_getschedpolicy -@cindex get scheduling policy - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_getschedpolicy( - const pthread_attr_t *attr, - int *policy -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The specified scheduler policy argument pointer is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_getschedpolicy} routine is used to obtain the -scheduler policy field from the thread attribute object @code{attr}. -The value of this field is returned in @code{policy}. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the -family of routines to which this routine belongs is supported. - -@c -@c -@c -@page -@subsection pthread_attr_setschedparam - Set Scheduling Parameters - -@findex pthread_attr_setschedparam -@cindex set scheduling parameters - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_setschedparam( - pthread_attr_t *attr, - const struct sched_param param -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The specified scheduler parameter argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_setschedparam} routine is used to set the -scheduler parameters field in the thread attribute object @code{attr} to -the value specified by @code{param}. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the -family of routines to which this routine belongs is supported. - -@c -@c -@c -@page -@subsection pthread_attr_getschedparam - Get Scheduling Parameters - -@findex pthread_attr_getschedparam -@cindex get scheduling parameters - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_attr_getschedparam( - const pthread_attr_t *attr, - struct sched_param *param -); -@end example - -@subheading STATUS CODES: -@table @b -@item EINVAL -The attribute pointer argument is invalid. - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The specified scheduler parameter argument pointer is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_getschedparam} routine is used to obtain the -scheduler parameters field from the thread attribute object @code{attr}. -The value of this field is returned in @code{param}. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the -family of routines to which this routine belongs is supported. - -@c -@c -@c -@page -@subsection pthread_attr_getaffinity_np - Get Thread Affinity Attribute - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#define _GNU_SOURCE -#include <pthread.h> - -int pthread_attr_getaffinity_np( - const pthread_attr_t *attr, - size_t cpusetsize, - cpu_set_t *cpuset -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EFAULT -The attribute pointer argument is invalid. - -@item EFAULT -The cpuset pointer argument is invalid. - -@item EINVAL -The @code{cpusetsize} does not match the value of @code{affinitysetsize} -field in the thread attribute object. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_getaffinity_np} routine is used to obtain the -@code{affinityset} field from the thread attribute object @code{attr}. -The value of this field is returned in @code{cpuset}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection pthread_attr_setaffinity_np - Set Thread Affinity Attribute - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#define _GNU_SOURCE -#include <pthread.h> - -int pthread_attr_setaffinity_np( - pthread_attr_t *attr, - size_t cpusetsize, - const cpu_set_t *cpuset -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EFAULT -The attribute pointer argument is invalid. - -@item EFAULT -The cpuset pointer argument is invalid. - -@item EINVAL -The @code{cpusetsize} does not match the value of @code{affinitysetsize} -field in the thread attribute object. - -@item EINVAL -The @code{cpuset} did not select a valid cpu. - -@item EINVAL -The @code{cpuset} selected a cpu that was invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_attr_setaffinity_np} routine is used to set the -@code{affinityset} field in the thread attribute object @code{attr}. -The value of this field is returned in @code{cpuset}. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection pthread_create - Create a Thread - -@findex pthread_create -@cindex create a thread - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_create( - pthread_t *thread, - const pthread_attr_t *attr, - void (*start_routine)( void *), - void *arg -); -@end example - -@subheading STATUS CODES: - -@table @b - -@item EINVAL -The attribute set is not initialized. - -@item EINVAL -The user specified a stack address and the size of the area was not -large enough to meet this processor's minimum stack requirements. - -@item EINVAL -The specified scheduler inheritance policy was invalid. - -@item ENOTSUP -The specified contention scope was PTHREAD_SCOPE_PROCESS. - -@item EINVAL -The specified thread priority was invalid. - -@item EINVAL -The specified scheduling policy was invalid. - -@item EINVAL -The scheduling policy was SCHED_SPORADIC and the specified replenishment -period is less than the initial budget. - -@item EINVAL -The scheduling policy was SCHED_SPORADIC and the specified low priority -is invalid. - -@item EAGAIN -The system lacked the necessary resources to create another thread, or the -self imposed limit on the total number of threads in a process -PTHREAD_THREAD_MAX would be exceeded. - -@item EINVAL -Invalid argument passed. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_create} routine is used to create a new thread with -the attributes specified by @code{attr}. If the @code{attr} argument -is @code{NULL}, then the default attribute set will be used. Modification -of the contents of @code{attr} after this thread is created does not -have an impact on this thread. - -The thread begins execution at the address specified by @code{start_routine} -with @code{arg} as its only argument. If @code{start_routine} returns, -then it is functionally equivalent to the thread executing the -@code{pthread_exit} service. - -Upon successful completion, the ID of the created thread is returned in the -@code{thread} argument. - -@subheading NOTES: - -There is no concept of a single main thread in RTEMS as there is in -a tradition UNIX system. POSIX requires that the implicit return of -the main thread results in the same effects as if there were a call -to @code{exit}. This does not occur in RTEMS. - -The signal mask of the newly created thread is inherited from its -creator and the set of pending signals for this thread is empty. - -@c -@c -@c -@page -@subsection pthread_exit - Terminate the Current Thread - -@findex pthread_exit -@cindex terminate the current thread - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -void pthread_exit( - void *status -); -@end example - -@subheading STATUS CODES: -@table @b -@item NONE - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_exit} routine is used to terminate the calling thread. -The @code{status} is made available to any successful join with the -terminating thread. - -When a thread returns from its start routine, it results in an -implicit call to the @code{pthread_exit} routine with the return -value of the function serving as the argument to @code{pthread_exit}. - -@subheading NOTES: - -Any cancellation cleanup handlers that hace been pushed and not yet popped -shall be popped in reverse of the order that they were pushed. After -all cancellation cleanup handlers have been executed, if the -thread has any thread-specific data, destructors for that data will -be invoked. - -Thread termination does not release or free any application visible -resources including byt not limited to mutexes, file descriptors, allocated -memory, etc.. Similarly, exitting a thread does not result in any -process-oriented cleanup activity. - -There is no concept of a single main thread in RTEMS as there is in -a tradition UNIX system. POSIX requires that the implicit return of -the main thread results in the same effects as if there were a call -to @code{exit}. This does not occur in RTEMS. - -All access to any automatic variables allocated by the threads is lost -when the thread exits. Thus references (i.e. pointers) to local variables -of a thread should not be used in a global manner without care. As -a specific example, a pointer to a local variable should NOT be used -as the return value. - - -@c -@c -@c -@page -@subsection pthread_detach - Detach a Thread - -@findex pthread_detach -@cindex detach a thread - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_detach( - pthread_t thread -); -@end example - -@subheading STATUS CODES: -@table @b -@item ESRCH -The thread specified is invalid. - -@item EINVAL -The thread specified is not a joinable thread. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_detach} routine is used to to indicate that storage -for @code{thread} can be reclaimed when the thread terminates without -another thread joinging with it. - -@subheading NOTES: - -If any threads have previously joined with the specified thread, then they -will remain joined with that thread. Any subsequent calls to -@code{pthread_join} on the specified thread will fail. - -@c -@c pthread_getattr_np -@c -@page -@subsection pthread_getattr_np - Get Thread Attributes - -@findex pthread_getattr_np -@cindex get thread attributes - -@subheading CALLING SEQUENCE: - -@example -#define _GNU_SOURCE -#include <pthread.h> - -int pthread_getattr_np( - pthread_t thread, - pthread_attr_t *attr -); -@end example - -@subheading STATUS CODES: -@table @b -@item ESRCH -The thread specified is invalid. - -@item EINVAL -The attribute pointer argument is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_getattr_np} routine is used to obtain the -attributes associated with @code{thread}. - -@subheading NOTES: - -Modification of the execution modes and priority through the Classic API -may result in a combination that is not representable in the POSIX API. - -@c -@c -@c -@page -@subsection pthread_join - Wait for Thread Termination - -@findex pthread_join -@cindex wait for thread termination - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_join( - pthread_t thread, - void **value_ptr -); -@end example - -@subheading STATUS CODES: -@table @b -@item ESRCH -The thread specified is invalid. - -@item EINVAL -The thread specified is not a joinable thread. - -@item EDEADLK -A deadlock was detected or thread is the calling thread. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_join} routine suspends execution of the calling thread -until @code{thread} terminates. If @code{thread} has already terminated, -then this routine returns immediately. The value returned by @code{thread} -(i.e. passed to @code{pthread_exit} is returned in @code{value_ptr}. - -When this routine returns, then @code{thread} has been terminated. - -@subheading NOTES: - -The results of multiple simultaneous joins on the same thread is undefined. - -If any threads have previously joined with the specified thread, then they -will remain joined with that thread. Any subsequent calls to -@code{pthread_join} on the specified thread will fail. - -If value_ptr is NULL, then no value is returned. - -@c -@c -@c -@page -@subsection pthread_self - Get Thread ID - -@findex pthread_self -@cindex get thread id - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -pthread_t pthread_self( void ); -@end example - -@subheading STATUS CODES: - -The value returned is the ID of the calling thread. - -@subheading DESCRIPTION: - -This routine returns the ID of the calling thread. - -@subheading NOTES: - -NONE - -@c -@c -@c -@page -@subsection pthread_equal - Compare Thread IDs - -@findex pthread_equal -@cindex compare thread ids - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_equal( - pthread_t t1, - pthread_t t2 -); -@end example - -@subheading STATUS CODES: - -@table @b -@item zero -The thread ids are not equal. - -@item non-zero -The thread ids are equal. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_equal} routine is used to compare two thread -IDs and determine if they are equal. - -@subheading NOTES: - -The behavior is undefined if the thread IDs are not valid. - -@c -@c -@c -@page -@subsection pthread_once - Dynamic Package Initialization - -@findex pthread_once -@cindex dynamic package initialization - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -pthread_once_t once_control = PTHREAD_ONCE_INIT; - -int pthread_once( - pthread_once_t *once_control, - void (*init_routine)(void) -); -@end example - -@subheading STATUS CODES: - -NONE - -@subheading DESCRIPTION: - -The @code{pthread_once} routine is used to provide controlled initialization -of variables. The first call to @code{pthread_once} by any thread with the -same @code{once_control} will result in the @code{init_routine} being -invoked with no arguments. Subsequent calls to @code{pthread_once} with -the same @code{once_control} will have no effect. - -The @code{init_routine} is guaranteed to have run to completion when -this routine returns to the caller. - -@subheading NOTES: - -The behavior of @code{pthread_once} is undefined if @code{once_control} -is automatic storage (i.e. on a task stack) or is not initialized using -@code{PTHREAD_ONCE_INIT}. - -@c -@c -@c -@page -@subsection pthread_setschedparam - Set Thread Scheduling Parameters - -@findex pthread_setschedparam -@cindex set thread scheduling parameters - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_setschedparam( - pthread_t thread, - int policy, - struct sched_param *param -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The scheduling parameters indicated by the parameter param is invalid. - -@item EINVAL -The value specified by policy is invalid. - -@item EINVAL -The scheduling policy was SCHED_SPORADIC and the specified replenishment -period is less than the initial budget. - -@item EINVAL -The scheduling policy was SCHED_SPORADIC and the specified low priority -is invalid. - -@item ESRCH -The thread indicated was invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_setschedparam} routine is used to set the -scheduler parameters currently associated with the thread specified -by @code{thread} to the policy specified by @code{policy}. The -contents of @code{param} are interpreted based upon the @code{policy} -argument. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the -family of routines to which this routine belongs is supported. - -@c -@c -@c -@page -@subsection pthread_getschedparam - Get Thread Scheduling Parameters - -@findex pthread_getschedparam -@cindex get thread scheduling parameters - -@subheading CALLING SEQUENCE: - -@example -#include <pthread.h> - -int pthread_getschedparam( - pthread_t thread, - int *policy, - struct sched_param *param -); -@end example - -@subheading STATUS CODES: - -@table @b -@item EINVAL -The policy pointer argument is invalid. - -@item EINVAL -The scheduling parameters pointer argument is invalid. - -@item ESRCH -The thread indicated by the parameter thread is invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_getschedparam} routine is used to obtain the -scheduler policy and parameters associated with @code{thread}. -The current policy and associated parameters values returned in -@code{policy} and @code{param}, respectively. - -@subheading NOTES: - -As required by POSIX, RTEMS defines the feature symbol -@code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the -family of routines to which this routine belongs is supported. - -@c -@c pthread_getaffinity_np -@c -@page -@subsection pthread_getaffinity_np - Get Thread Affinity - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#define _GNU_SOURCE -#include <pthread.h> - -int pthread_getaffinity_np( - const pthread_t id, - size_t cpusetsize, - cpu_set_t *cpuset -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EFAULT -The cpuset pointer argument is invalid. - -@item EINVAL -The @code{cpusetsize} does not match the value of @code{affinitysetsize} -field in the thread attribute object. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_getaffinity_np} routine is used to obtain the -@code{affinity.set} field from the thread control object associated -with the @code{id}. The value of this field is returned in @code{cpuset}. - -@subheading NOTES: - -NONE - -@c -@c pthread_setaffinity_np -@c -@page -@subsection pthread_setaffinity_np - Set Thread Affinity - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#define _GNU_SOURCE -#include <pthread.h> - -int pthread_setaffinity_np( - pthread_t id, - size_t cpusetsize, - const cpu_set_t *cpuset -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EFAULT -The cpuset pointer argument is invalid. - -@item EINVAL -The @code{cpusetsize} does not match the value of @code{affinitysetsize} -field in the thread attribute object. - -@item EINVAL -The @code{cpuset} did not select a valid cpu. - -@item EINVAL -The @code{cpuset} selected a cpu that was invalid. - -@end table - -@subheading DESCRIPTION: - -The @code{pthread_setaffinity_np} routine is used to set the -@code{affinityset} field of the thread object @code{id}. -The value of this field is returned in @code{cpuset} - -@subheading NOTES: - -NONE diff --git a/doc/posix_users/timer.t b/doc/posix_users/timer.t deleted file mode 100644 index 6ee3e5c808..0000000000 --- a/doc/posix_users/timer.t +++ /dev/null @@ -1,193 +0,0 @@ -@c -@c This is the chapter from the RTEMS POSIX 1003.1b API User's Guide that -@c documents the services provided by the timer @c manager. - -@chapter Timer Manager - -@section Introduction - -The timer manager is ... - -The services provided by the timer manager are: - -@itemize @bullet -@item @code{timer_create} - Create a Per-Process Timer -@item @code{timer_delete} - Delete a Per-Process Timer -@item @code{timer_settime} - Set Next Timer Expiration -@item @code{timer_gettime} - Get Time Remaining on Timer -@item @code{timer_getoverrun} - Get Timer Overrun Count -@end itemize - -@section Background - -@section Operations - -@section System Calls - -This section details the timer manager's services. -A subsection is dedicated to each of this manager's services -and describes the calling sequence, related constants, usage, -and status codes. - - -@c -@c timer_create -@c - -@page -@subsection timer_create - Create a Per-Process Timer - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <time.h> -#include <signal.h> - -int timer_create( - clockid_t clock_id, - struct sigevent *evp, - timer_t *timerid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c timer_delete -@c - -@page -@subsection timer_delete - Delete a Per-Process Timer - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <time.h> - -int timer_delete( - timer_t timerid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c timer_settime -@c - -@page -@subsection timer_settime - Set Next Timer Expiration - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <time.h> - -int timer_settime( - timer_t timerid, - int flags, - const struct itimerspec *value, - struct itimerspec *ovalue -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c timer_gettime -@c - -@page -@subsection timer_gettime - Get Time Remaining on Timer - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <time.h> - -int timer_gettime( - timer_t timerid, - struct itimerspec *value -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - - -@c -@c timer_getoverrun -@c - -@page -@subsection timer_getoverrun - Get Timer Overrun Count - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include <time.h> - -int timer_getoverrun( - timer_t timerid -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{EXXX} - - -@subheading DESCRIPTION: - -@subheading NOTES: - diff --git a/doc/posix_users/version.texi b/doc/posix_users/version.texi deleted file mode 100644 index c0e4bbb7b6..0000000000 --- a/doc/posix_users/version.texi +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 17 July 2015 -@set UPDATED-MONTH July 2015 -@set EDITION 4.10.99.0 -@set VERSION 4.10.99.0 |