Add a new "Inter-Process Communication" chapter.

This patch adds a new "Inter-Process Communication"
chapter to cover the sem*, msg*, and shm* functions.
Initially we document only the sem* function signatures
and their safety notes.

diff --git a/ChangeLog b/ChangeLog
index 02ca836..9505934 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2014-02-26  Carlos O'Donell  <carlos@redhat.com>
+
+       * manual/ipc.texi: New file.
+       * manual/Makefile (chapters): Add ipc.
+       * manual/job.texi: Add "Inter-Process Communication" to next.
+       * manual/process.texi: Add "Inter-Process Communication" to prev.
+
 2014-02-26  Adhemerval Zanella  <azanella@linux.vnet.ibm.com>
 
        * sysdeps/powerpc/fpu/libm-test-ulps: Update.

diff --git a/manual/Makefile b/manual/Makefile
index 5f98b2a..1129136 100644 (file)
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -41,8 +41,8 @@ chapters = $(addsuffix .texi, \
                       intro errno memory ctype string charset locale   \
                       message search pattern io stdio llio filesys     \
                       pipe socket terminal syslog math arith time      \
-                      resource setjmp signal startup process job nss   \
-                      users sysinfo conf crypt debug threads probes)
+                      resource setjmp signal startup process ipc job   \
+                      nss users sysinfo conf crypt debug threads probes)
 add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi))
 appendices = lang.texi header.texi install.texi maint.texi platform.texi \
             contrib.texi

diff --git a/manual/ipc.texi b/manual/ipc.texi
new file mode 100644 (file)
index 0000000..3cd573e
--- /dev/null
+++ b/manual/ipc.texi
@@ -0,0 +1,116 @@
+@node Inter-Process Communication, Job Control, Processes, Top
+@c %MENU% All about inter-process communication
+@chapter Inter-Process Communication
+@cindex ipc
+
+This chapter describes the @glibcadj{} inter-process communication primitives.
+
+@menu
+* Semaphores:: Support for creating and managing semaphores
+@end menu
+
+@node Semaphores
+@section Semaphores
+
+The @glibcadj{} implements the semaphore APIs as defined in POSIX and
+System V.  Semaphores can be used by multiple processes to coordinate shared
+resources.  The following is a complete list of the semaphore functions provided
+by @theglibc{}.
+
+@c Need descriptions for all of these functions.
+
+@subsection System V Semaphores
+@deftypefun int semctl (int @var{semid}, int @var{semnum}, int @var{cmd});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{/linux}}}
+@c syscall(ipc) ok
+@c
+@c AC-unsafe because we need to translate the new kernel
+@c semid_ds buf into the userspace layout.  Cancellation
+@c at that point results in an inconsistent userspace
+@c semid_ds.
+@end deftypefun
+
+@deftypefun int semget (key_t @var{key}, int @var{nsems}, int @var{semflg});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c syscall(ipc) ok
+@end deftypefun
+
+@deftypefun int semop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c syscall(ipc) ok
+@end deftypefun
+
+@deftypefun int semtimedop (int @var{semid}, struct sembuf *@var{sops}, size_t @var{nsops}, const struct timespec *@var{timeout});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c syscall(ipc) ok
+@end deftypefun
+
+@subsection POSIX Semaphores
+
+@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+@c Does not atomically update sem_t therefore AC-unsafe
+@c because it can leave sem_t partially initialized.
+@end deftypefun
+
+@deftypefun int sem_destroy (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Function does nothing and is therefore always safe.
+@end deftypefun
+
+@deftypefun sem_t *sem_open (const char *@var{name}, int @var{oflag}, ...);
+@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}}
+@c pthread_once asuinit
+@c
+@c We are AC-Unsafe becuase we use pthread_once to initialize
+@c a global variable that holds the location of the mounted
+@c shmfs on Linux.
+@end deftypefun
+
+@deftypefun int sem_close (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@asucorrupt{}}}
+@c lll_lock asulock aculock
+@c twalk asucorrupt
+@c
+@c We are AS-unsafe because we take a non-recursive lock.
+@c We are AC-unsafe because several internal data structures
+@c are not updated atomically.
+@end deftypefun
+
+@deftypefun int sem_unlink (const char *@var{name});
+@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}}
+@c pthread_once asuinit acucorrupt aculock
+@c mempcpy acucorrupt
+@end deftypefun
+
+@deftypefun int sem_wait (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+@c atomic_increment (nwaiters) acucorrupt
+@c
+@c Given the use atomic operations this function seems
+@c to be AS-safe.  It is AC-unsafe because there is still
+@c a window between atomic_decrement and the pthread_push
+@c of the handler that undoes that operation.  A cancellation
+@c at that point would fail to remove the process from the
+@c waiters count.
+@end deftypefun
+
+@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime});
+@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
+@c Same safety issues as sem_wait.
+@end deftypefun
+
+@deftypefun int sem_trywait (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c All atomic operations are safe in all contexts.
+@end deftypefun
+
+@deftypefun int sem_post (sem_t *@var{sem});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Same safety as sem_trywait.
+@end deftypefun
+
+@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval});
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Atomic write of a value is safe in all contexts.
+@end deftypefun

diff --git a/manual/job.texi b/manual/job.texi
index 4e58f54..4f9bd81 100644 (file)
--- a/manual/job.texi
+++ b/manual/job.texi
@@ -1,4 +1,4 @@
-@node Job Control, Name Service Switch, Processes, Top
+@node Job Control, Name Service Switch, Inter-Process Communication, Top
 @c %MENU% All about process groups and sessions
 @chapter Job Control
 

diff --git a/manual/process.texi b/manual/process.texi
index aee65b9..aa59040 100644 (file)
--- a/manual/process.texi
+++ b/manual/process.texi
@@ -1,4 +1,4 @@
-@node Processes, Job Control, Program Basics, Top
+@node Processes, Inter-Process Communication, Program Basics, Top
 @c %MENU% How to create processes and run other programs
 @chapter Processes