aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCarlos O'Donell <carlos@redhat.com>2014-02-26 11:03:24 -0500
committerCarlos O'Donell <carlos@redhat.com>2014-02-26 11:05:09 -0500
commit085d0e354a84807ca97f8720e532763bd4bfa933 (patch)
treedbf9cf2d75b6609e96445ef2d726d8dec27fb964
parent86e58c0815260c64db5d6469412c0ecdc8ffc8e5 (diff)
downloadglibc-085d0e354a84807ca97f8720e532763bd4bfa933.zip
glibc-085d0e354a84807ca97f8720e532763bd4bfa933.tar.gz
glibc-085d0e354a84807ca97f8720e532763bd4bfa933.tar.bz2
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.
-rw-r--r--ChangeLog7
-rw-r--r--manual/Makefile4
-rw-r--r--manual/ipc.texi116
-rw-r--r--manual/job.texi2
-rw-r--r--manual/process.texi2
5 files changed, 127 insertions, 4 deletions
diff --git a/ChangeLog b/ChangeLog
index 02ca836..9505934 100644
--- 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
--- 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
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
--- 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
--- 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