-.TH SEMEX 1 "July 10, 1992"
-.SH NAME
-semex -- exerciser for System V semaphore operations
-.SH SYNOPSIS
-semex
-.SH DESCRIPTION
-This is an interactive exerciser for the semctl(2), semget(2) and
-semop(2) system calls of System V UNIX. You can use it to experiment with
-the semaphore features in order to understand them better. It includes
-on-line help.
-.PP
-Calls that might cause semex to block (semop(2) with negative operation
-values) are handed to a forked copy of semex. Semex's children emit reports
-just before they block and when they unblock, to enable the user to track
-what's going on.
-.PP
-Semex can also be used as a semaphores interface for scripts. Command
-prompting is suppressed if stdin isn't a tty; so are the verbose
-descriptions of actions performed that it normally emits, and the
-process-forking described above.
-.SH COMMANDS
-All arguments of every command are optional; the code tries to give
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<!-- lifted from troff+man by doclifter -->
+<refentry id='semex.1'>
+<refmeta>
+<refentrytitle>SEMEX</refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class='date'>July 10, 1992</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>semex </refname>
+<refpurpose> exerciser for System V semaphore operations</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+
+<cmdsynopsis>
+ <command>semex</command>
+</cmdsynopsis>
+
+</refsynopsisdiv>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+
+<para>This is an interactive exerciser for the
+<citerefentry><refentrytitle>semctl/refentrytitle><manvolnum>2</manvolnum></citerefentry>,
+<citerefentry><refentrytitle>semget/refentrytitle><manvolnum>2</manvolnum></citerefentry>
+and
+<citerefentry><refentrytitle>semop/refentrytitle><manvolnum>2</manvolnum></citerefentry>
+system calls of System V UNIX. You can use it to experiment with the
+semaphore features in order to understand them better. It includes
+on-line help.</para>
+
+<para>Calls that might cause <command>semex</command> to block
+(<citerefentry><refentrytitle>semop/refentrytitle><manvolnum>2</manvolnum></citerefentry>
+with negative operation values) are handed to a forked copy of
+semex. Semex's children emit reports just before they block and when
+they unblock, to enable the user to track what's going on.</para>
+
+<para>Semex can also be used as a semaphores interface for
+scripts. Command prompting is suppressed if stdin isn't a tty; so are
+the verbose descriptions of actions performed that it normally emits,
+and the process-forking described above.</para> </refsect1>
+
+<refsect1 id='commands'><title>COMMANDS</title>
+
+<para>All arguments of every command are optional; the code tries to give
reasonable defaults to any you leave off. Anytime a `semid' or `semnum'
argument is given, the default semid or semnum for future commands is set
-to it.
+to it.</para>
- c(reate) key nsems -[ce] perms -- create semaphore group
+<para> c(reate) key nsems -[ce] perms -- create semaphore group</para>
-This calls semget(2). The `key' argument should be a long, the `nsems'
-argument an int. The third (flags) argument of the semget(2) call is
-created from the third and fourth arguments of this command; flags
-`c' and `e' stand for IPC_CREAT and IPC_EXCL respectively and `perms'
-should be at least three digits of octal permission mask.
-.PP
-The `current semaphore group id' (semid) is set to the return value
-of this command.
-.PP
-The default arguments are `0L 1 - 0660' (note that 0L = IPC_PRIVATE).
+<para>This calls
+<citerefentry><refentrytitle>semget/refentrytitle><manvolnum>2</manvolnum></citerefentry>. The
+`key' argument should be a long, the `nsems' argument an int. The
+third (flags) argument of the
+<citerefentry><refentrytitle>semget/refentrytitle><manvolnum>2</manvolnum></citerefentry>
+call is created from the third and fourth arguments of this command;
+flags `c' and `e' stand for IPC_CREAT and IPC_EXCL respectively and
+`perms' should be at least three digits of octal permission
+mask.</para>
- f(ind) semid -- select a semaphore group by id
+<para>The `current semaphore group id' (semid) is set to the return value
+of this command. </para>
-This changes semex's notion of the current semaphore group id. If the
-argument is omitted, the current value is simply printed out.
+<para>The default arguments are `0L 1 - 0660' (note that 0L =
+IPC_PRIVATE).</para>
- i(ndex) semnum -- select a semaphore index
+<para> f(ind) semid -- select a semaphore group by id</para>
-This changes semex's notion of the current semaphore index. If the
-argument is omitted, the current value is simply printed out.
+<para>This changes semex's notion of the current semaphore group id. If the
+argument is omitted, the current value is simply printed out.</para>
- d(o) op -[un] -- do a semaphore operation
+<para> i(ndex) semnum -- select a semaphore index</para>
-This command does a semop(2) call. The first argument of the call will
-be the currently selected semaphore id. The third argument (number of
-operations) will be 1. The (struct sembuf *) second argument will point
-to a single operation structure.
-.PP
-The sem_num field of this structure is set to the `current semaphore
+<para>This changes semex's notion of the current semaphore index. If the
+argument is omitted, the current value is simply printed out.</para>
+
+<para> d(o) op -[un] -- do a semaphore operation</para>
+
+<para>This command does a
+<citerefentry><refentrytitle>semop/refentrytitle><manvolnum>2</manvolnum></citerefentry>
+call. The first argument of the call will be the currently selected
+semaphore id. The third argument (number of operations) will be 1. The
+(struct sembuf *) second argument will point to a single operation
+structure.</para>
+
+<para>The sem_num field of this structure is set to the `current semaphore
index' value set by the `n' command (normally 1). The sem_op field is set
to the value of the `op' command argument (which should be an integer). The
sem_flg field is set according to the flags in the third command argument;
-`u' stands for SEM_UNDO, `n' for IPC_NOWAIT.
-.PP
-The argument defaults are `0 -'.
+`u' stands for SEM_UNDO, `n' for IPC_NOWAIT.</para>
- v(alue) semid semnum -- query a semaphore's semval
+<para>The argument defaults are `0 -'.</para>
-This command displays the return of a semctl(semid, semnum, GETVAL). If
+<para> v(alue) semid semnum -- query a semaphore's semval</para>
+
+<para>This command displays the return of a semctl(semid, semnum, GETVAL). If
semnum is omitted it defaults to the currently selected semaphore index. If
-semid is omitted it defaults to the currently selected semaphore id.
+semid is omitted it defaults to the currently selected semaphore id.</para>
- p(id) semid semnum -- query a semaphore's sempid
+<para> p(id) semid semnum -- query a semaphore's sempid</para>
-This command displays the return of a semctl(semid, semnum, GETPID). If
+<para>This command displays the return of a semctl(semid, semnum, GETPID). If
semnum is omitted it defaults to the currently selected semaphore index. If
-semid is omitted it defaults to the currently selected semaphore id.
+semid is omitted it defaults to the currently selected semaphore id.</para>
- n(cnt) semid semnum -- query a semaphore's semncnt
+<para> n(cnt) semid semnum -- query a semaphore's semncnt</para>
-This command displays the return of a semctl(semid, semnum, GETNCNT). If
+<para>This command displays the return of a semctl(semid, semnum, GETNCNT). If
semnum is omitted it defaults to the currently selected semaphore index. If
-semid is omitted it defaults to the currently selected semaphore id.
+semid is omitted it defaults to the currently selected semaphore id.</para>
- z(cnt) semid semnum -- query a semaphore's semzcnt
+<para> z(cnt) semid semnum -- query a semaphore's semzcnt</para>
-This command displays the return of a semctl(semid, semnum, GETZCNT). If
+<para>This command displays the return of a semctl(semid, semnum, GETZCNT). If
semnum is omitted it defaults to the currently selected semaphore index. If
-semid is omitted it defaults to the currently selected semaphore id.
+semid is omitted it defaults to the currently selected semaphore id.</para>
- s(et) semval -- set the value of a semaphore
+<para> s(et) semval -- set the value of a semaphore</para>
-This command does a semop(2) call using the SETVAL command to set
-the value of the currently selected semaphore. The first argument of the call
-will be the currently selected semaphore id. The second argument of the call
-will be the currently selected semaphore index. The fourth (value) argument
-will be the semval argument of the command (which defaults to 0 if omitted).
+<para>This command does a
+<citerefentry><refentrytitle>semop/refentrytitle><manvolnum>2</manvolnum></citerefentry>
+call using the SETVAL command to set the value of the currently
+selected semaphore. The first argument of the call will be the
+currently selected semaphore id. The second argument of the call will
+be the currently selected semaphore index. The fourth (value) argument
+will be the semval argument of the command (which defaults to 0 if
+omitted).</para>
- m(mask) semid uid gid mode -- query/set a semaphore's mode
+<para> m(mask) semid uid gid mode -- query/set a semaphore's mode</para>
-The m command with no arguments displays the uid, gid and mode
+<para>The m command with no arguments displays the uid, gid and mode
of the currently selected semaphore group. With one argument, it displays
this information for the given semaphore group. With two or more arguments
it sets whatever portions of the mode and ownership data are given; uid and
-gid should be decimal integers and mode at least three digits of octal.
+gid should be decimal integers and mode at least three digits of octal.</para>
+
+<para> r(emove) semid -- remove a semaphore group</para>
- r(emove) semid -- remove a semaphore group
+<para>Do a
+<citerefentry><refentrytitle>semctl/refentrytitle><manvolnum>2</manvolnum></citerefentry>
+to remove a semaphore group. If the semid argument is omitted, the
+currently selected semaphore group will be removed.</para>
-Do a semctl(2) to remove a semaphore group. If the semid argument is
-omitted, the currently selected semaphore group will be removed.
+<para> l(ist) -- run ipcs -sbopt</para>
- l(ist) -- run ipcs -sbopt
+<para>This is just a convenience. It displays data on active semaphores.</para>
-This is just a convenience. It displays data on active semaphores.
+<para> x(it) -- exit</para>
- x(it) -- exit
+<para>Exit semex. Child <command>semex</command> processes created by
+'d' commands will get SIGHUP and die gracefully.</para>
-Exit semex. Child semex processes created by 'd' commands will get SIGHUP
-and die gracefully.
+<para> ! cmd -- execute a shell command</para>
- ! cmd -- execute a shell command
+<para>Escape to a shell. </para>
-Escape to a shell.
+<para> ? -- print this help message</para>
- ? -- print this help message
+<para>In addition, typing a newline will simply display the value of the
+currently selected semaphore (newline is a synonym for the `v' command).</para>
+</refsect1>
-In addition, typing a newline will simply display the value of the
-currently selected semaphore (newline is a synonym for the `v' command).
-.SH NOTE
-The AT&T documentation entries for semop(2) tell lies about the type of
-the second argument. System V Release 1 claims the type is
+<refsect1 id='bugs'><title>BUGS</title>
+<para>The 'p' and 'v' commands are not Dyskstra's P and V operations.</para>
- struct sembuf (*)[]
+<para>There is no way for <command>semex</command> to specify more
+than one semaphore op at once in
+<citerefentry><refentrytitle>semop/refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
-and its lint library entry is correspondingly broken. Release 2 claims
-that the type is
+<para>There is no support for exercising the GETALL or SETALL modes of
+<citerefentry><refentrytitle>semctl/refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
- struct sembuf **
+</refsect1>
-but its lint library checks for the correct type, which is
+<refsect1 id='author'><title>AUTHOR</title>
- struct sembuf *
+<para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>. You may
+find updates and related resources at <ulink
+url='http://www.tuxedo.org/~esr/'>http://www.tuxedo.org/~esr/</ulink>.</para>
-as one can actually deduce from the description text for both entries.
-System V Release 3 and 4 and Linux all seem to get this right.
-.SH BUGS
-The 'p' and 'v' commands are not Dyskstra's P and V operations.
-.PP
-There is no way for semex to specify more than one semaphore op at once
-in semop(2).
-.PP
-There is no support for exercising the GETALL or SETALL modes of semctl(2).
-.SH AUTHOR
-Eric S. Raymond <esr@snark.thyrsus.com>. You may find updates and related
-resources at http://www.ccil.org/~esr/home.html.
+</refsect1>
+</refentry>
projects / semex.git / commitdiff