semget.2: EXAMPLE: add an example program

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/semget.2

@@ -1,4 +1,5 @@
 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
+.\" and Copyright (C) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
 .\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
@@ -312,6 +313,147 @@ The name choice
 was perhaps unfortunate,
 .B IPC_NEW
 would more clearly show its function.
+.SH EXAMPLE
+The program shown below uses
+.BR semget ()
+to create a new semaphore set or retrieve the ID of an existing set.
+It generates the
+.I key
+for
+.BR semget ()
+using
+.BR ftok (3).
+The first two command-line arguments are used as the
+.I pathname
+and
+.I proj_id
+arguments for
+.BR ftok (3).
+The third command-line argument is an integer that specifies the
+.I nsems
+argument for
+.BR semget ().
+Command-line options can be used to specify the
+.BR IPC_CREAT
+.RI ( \-c )
+and
+.BR IPC_EXCL
+.RI ( \-x )
+flags for the call to
+.BR semget ().
+The usage of this program is demonstrated below.
+.PP
+We first create two files that will be used to generate keys using
+.BR ftok (3),
+create two semaphore sets using those files, and then list the sets using
+.BR ipcs (1):
+.PP
+.in +4n
+.EX
+$ \fBtouch mykey mykey2\fP
+$ \fB./t_semget \-c mykey p 1\fP
+ID = 9
+$ \fB./t_semget \-c mykey2 p 2\fP
+ID = 10
+$ \fBipcs \-s\fP
+
+\-\-\-\-\-\- Semaphore Arrays \-\-\-\-\-\-\-\-
+key        semid      owner      perms      nsems
+0x7004136d 9          mtk        600        1
+0x70041368 10         mtk        600        2
+.EE
+.in
+.PP
+Next, we demonstrate that when
+.BR semctl ()
+is given the same
+.I key
+(as generated by the same arguments to
+.BR ftok (3)),
+it returns the ID of the already existing semaphore set:
+.PP
+.in +4n
+.EX
+$ \fB./t_semget \-c mykey p 1\fP
+ID = 9
+.EE
+.in
+.PP
+Finally, we demonstrate the kind of collision that can occur when
+.BR ftok (3)
+is given different
+.I pathname
+arguments that have the same inode number:
+.PP
+.in +4n
+.EX
+$ \fBln mykey link\fP
+$ \fBls \-i1 link mykey\fP
+2233197 link
+2233197 mykey
+$ \fB./t_semget link p 1\fP       # Generates same key as \(aqmykey\(aq
+ID = 9
+.EE
+.in
+.PP
+.SS Program source
+\&
+.nf
+#include <sys/types.h>
+#include <sys/ipc.h>
+#include <sys/sem.h>
+#include <sys/stat.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+
+static void
+usage(const char *pname)
+{
+    fprintf(stderr, "Usage: %s [\-cx] pathname proj\-id num\-sems\en",
+            pname);
+    fprintf(stderr, "    \-c           Use IPC_CREAT flag\en");
+    fprintf(stderr, "    \-x           Use IPC_EXCL flag\en");
+    exit(EXIT_FAILURE);
+}
+
+int
+main(int argc, char *argv[])
+{
+    int semid, nsems, flags, opt;
+    key_t key;
+
+    flags = 0;
+    while ((opt = getopt(argc, argv, "cx")) != \-1) {
+        switch (opt) {
+        case \(aqc\(aq: flags |= IPC_CREAT;   break;
+        case \(aqx\(aq: flags |= IPC_EXCL;    break;
+        default:  usage(argv[0]);
+        }
+    }
+
+    if (argc != optind + 3)
+        usage(argv[0]);
+
+    key = ftok(argv[optind], argv[optind + 1][0]);
+    if (key == \-1) {
+        perror("ftok");
+        exit(EXIT_FAILURE);
+    }
+
+    nsems = atoi(argv[optind + 2]);
+
+    semid = semget(key, nsems, flags | 0600);
+    if (semid == \-1) {
+        perror("semget");
+        exit(EXIT_FAILURE);
+    }
+
+    printf("ID = %d\en", semid);
+
+    exit(EXIT_SUCCESS);
+}
+.fi
 .SH SEE ALSO
 .BR semctl (2),
 .BR semop (2),