Manual may mislead many mighty men.

[Dave Decot]

> A pal of mine was trying to use semaphores on a Sys V Rel 3 system,
> yesterday, and was having trouble with the semop() command.
> 
> To quote from the manual,
> int semop(semid, sops, nsops)
> int semid;
> struct sembuf **sops;
> int nsops;

The above is incorrect, and probably based on a misunderstanding of some
bad documentation (probably the bad documentation is on the same page).

> while my program had,
> 
> struct sembuf sops[10];
>    rtrn = semop(semid, sops, nsops);

The above is completely correct.

> Looked up "Adv. Unix Prog." (Marc J. Rochkind) - Prentice Hall.
> 
> On pg 188, he says (prob. from the manual):
> int semop(sid, ops, nops)
> int sid;
> struct sembuf (*ops)[];
> int nops;

The above is wrong, and is probably based on a misunderstanding of
the misused phrase "a pointer to an array" (see below).

> However, the program on pg. 190  goes:
>   struct sembuf sb;
>   semop(semid, &sb, 1);

The above works, because you are using an "array" of size 1, and the
"name" of your "array" is &sb.  This would also work:

struct sembuf sb[1];
semop(semid, sb, 1);

> 
> Finally, checked up "The Design of the UNIX operating system"  (Maurice
> J. Bach)  - Prentice-Hall.
> On pg. 373 he says, "...oplist is a pointer to an array of semaphore
> operations ..." 
> (It should be " oplist is an array of ..." ?)

No, it *should* be "oplist is a pointer to the first element of an array of
semaphore operations" if oplist is the name of the second argument
to semop().  Remember that it's impossible to pass arrays to functions.
The phrase "pointer to an array of" is often misused when "pointer to
the first element of an array of" is meant, even in classic holy
scriptures.  The reason "everyone understands it" is because types of
the form "pointer to an array of" are much less often used.

Here's a "pointer to an array of 10 characters":

  int (*p)[10];

As a parameter declaration, here's a "pointer to the first element of
an array of 10 characters":

  int p[10];

However, most compilers ignore the 10 since it is irrelevant.  In fact,
I'm not even sure sizeof(p) even cares about the 10.

> The prog. in Fig 11.14 gives:
> struct sembuf  psembuf, vsembuf;
> semop(semid, &psembuf, 1);
> semop(semid, &vsembuf, 1);

These are correct, because you are using semaphore sets of size 1.
A pointer to a variable of a certain type works just as fine as
a pointer to the first element of an array containing one element
of that type.

> PS: Just check the SUN man pages; seems to be the right way: 
> int semop(semid, sops, nsops)
> int semid;
> struct sembuf *sops;
> int nsops;

That is a correct declaration.  HP-UX has it correct as well.

Dave Decot