}
Practical hint: you almost never need to use C<eof> in Perl, because the
-input operators return C<undef> when they run out of data.
+input operators return false values when they run out of data, or if there
+was an error.
=item eval EXPR
use Fcntl;
-first to get the correct function definitions. Argument processing and
+first to get the correct constant definitions. Argument processing and
value return works just like ioctl() below.
For example:
=item getc
Returns the next character from the input file attached to FILEHANDLE,
-or a null string at end of file. If FILEHANDLE is omitted, reads from STDIN.
-This is not particularly efficient. It cannot be used to get unbuffered
-single-characters, however. For that, try something more like:
+or the undefined value at end of file, or if there was an error. If
+FILEHANDLE is omitted, reads from STDIN. This is not particularly
+efficient. It cannot be used to get unbuffered single-characters,
+however. For that, try something more like:
if ($BSD_STYLE) {
system "stty cbreak </dev/tty >/dev/tty 2>&1";
=item msgctl ID,CMD,ARG
-Calls the System V IPC function msgctl(2). If CMD is &IPC_STAT, then ARG
-must be a variable that will hold the returned msqid_ds structure.
-Returns like ioctl: the undefined value for error, "0 but true" for
-zero, or the actual return value otherwise.
+Calls the System V IPC function msgctl(2). You'll probably have to say
+
+ use IPC::SysV;
+
+first to get the correct constant definitions. If CMD is IPC_STAT,
+then ARG must be a variable which will hold the returned msqid_ds
+structure. Returns like ioctl: the undefined value for error, "0 but
+true" for zero, or the actual return value otherwise. See also
+IPC::SysV and IPC::Semaphore::Msg documentation.
=item msgget KEY,FLAGS
-Calls the System V IPC function msgget(2). Returns the message queue id,
-or the undefined value if there is an error.
+Calls the System V IPC function msgget(2). Returns the message queue
+id, or the undefined value if there is an error. See also IPC::SysV
+and IPC::SysV::Msg documentation.
=item msgsnd ID,MSG,FLAGS
Calls the System V IPC function msgsnd to send the message MSG to the
message queue ID. MSG must begin with the long integer message type,
which may be created with C<pack("l", $type)>. Returns TRUE if
-successful, or FALSE if there is an error.
+successful, or FALSE if there is an error. See also IPC::SysV
+and IPC::SysV::Msg documentation.
=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
Calls the System V IPC function msgrcv to receive a message from
message queue ID into variable VAR with a maximum message size of
-SIZE. Note that if a message is received, the message type will be the
-first thing in VAR, and the maximum length of VAR is SIZE plus the size
-of the message type. Returns TRUE if successful, or FALSE if there is
-an error.
+SIZE. Note that if a message is received, the message type will be
+the first thing in VAR, and the maximum length of VAR is SIZE plus the
+size of the message type. Returns TRUE if successful, or FALSE if
+there is an error. See also IPC::SysV and IPC::SysV::Msg documentation.
=item my EXPR
=item read FILEHANDLE,SCALAR,LENGTH
Attempts to read LENGTH bytes of data into variable SCALAR from the
-specified FILEHANDLE. Returns the number of bytes actually read, or
-undef if there was an error. SCALAR will be grown or shrunk to the
-length actually read. An OFFSET may be specified to place the read
-data at some other place than the beginning of the string. This call
-is actually implemented in terms of stdio's fread(3) call. To get a true
-read(2) system call, see sysread().
+specified FILEHANDLE. Returns the number of bytes actually read,
+C<0> at end of file, or undef if there was an error. SCALAR will be grown
+or shrunk to the length actually read. An OFFSET may be specified to
+place the read data at some other place than the beginning of the
+string. This call is actually implemented in terms of stdio's fread(3)
+call. To get a true read(2) system call, see sysread().
=item readdir DIRHANDLE
=item semctl ID,SEMNUM,CMD,ARG
-Calls the System V IPC function semctl. If CMD is &IPC_STAT or
-&GETALL, then ARG must be a variable that will hold the returned
+Calls the System V IPC function semctl. You'll probably have to say
+
+ use IPC::SysV;
+
+first to get the correct constant definitions. If CMD is IPC_STAT or
+GETALL, then ARG must be a variable which will hold the returned
semid_ds structure or semaphore value array. Returns like ioctl: the
undefined value for error, "0 but true" for zero, or the actual return
-value otherwise.
+value otherwise. See also IPC::SysV and IPC::Semaphore documentation.
=item semget KEY,NSEMS,FLAGS
Calls the System V IPC function semget. Returns the semaphore id, or
-the undefined value if there is an error.
+the undefined value if there is an error. See also IPC::SysV and
+IPC::SysV::Semaphore documentation.
=item semop KEY,OPSTRING
$semop = pack("sss", $semnum, -1, 0);
die "Semaphore trouble: $!\n" unless semop($semid, $semop);
-To signal the semaphore, replace "-1" with "1".
+To signal the semaphore, replace "-1" with "1". See also IPC::SysV
+and IPC::SysV::Semaphore documentation.
=item send SOCKET,MSG,FLAGS,TO
=item shmctl ID,CMD,ARG
-Calls the System V IPC function shmctl. If CMD is &IPC_STAT, then ARG
-must be a variable that will hold the returned shmid_ds structure.
-Returns like ioctl: the undefined value for error, "0 but true" for
-zero, or the actual return value otherwise.
+Calls the System V IPC function shmctl. You'll probably have to say
+
+ use IPC::SysV;
+
+first to get the correct constant definitions. If CMD is IPC_STAT,
+then ARG must be a variable which will hold the returned shmid_ds
+structure. Returns like ioctl: the undefined value for error, "0 but
+true" for zero, or the actual return value otherwise.
+See also IPC::SysV documentation.
=item shmget KEY,SIZE,FLAGS
Calls the System V IPC function shmget. Returns the shared memory
segment id, or the undefined value if there is an error.
+See also IPC::SysV documentation.
=item shmread ID,VAR,POS,SIZE
hold the data read. When writing, if STRING is too long, only SIZE
bytes are used; if STRING is too short, nulls are written to fill out
SIZE bytes. Return TRUE if successful, or FALSE if there is an error.
+See also IPC::SysV documentation.
=item shutdown SOCKET,HOW
replaces them with the elements of LIST, if any. In list context,
returns the elements removed from the array. In scalar context,
returns the last element removed, or C<undef> if no elements are
-removed. The array grows or shrinks as necessary. If LENGTH is
-omitted, removes everything from OFFSET onward. The following
-equivalences hold (assuming C<$[ == 0>):
+removed. The array grows or shrinks as necessary.
+If OFFSET is negative then it start that far from the end of the array.
+If LENGTH is omitted, removes everything from OFFSET onward.
+If LENGTH is negative, leave that many elements off the end of the array.
+The following equivalences hold (assuming C<$[ == 0>):
- push(@a,$x,$y) splice(@a,$#a+1,0,$x,$y)
+ push(@a,$x,$y) splice(@a,@a,0,$x,$y)
pop(@a) splice(@a,-1)
shift(@a) splice(@a,0,1)
unshift(@a,$x,$y) splice(@a,0,0,$x,$y)
An alternative to using substr() as an lvalue is to specify the
replacement string as the 4th argument. This allows you to replace
parts of the EXPR and return what was there before in one operation.
-In this case LEN can be C<undef> if you want to affect everything to
-the end of the string.
=item symlink OLDFILE,NEWFILE
specified FILEHANDLE, using the system call read(2). It bypasses
stdio, so mixing this with other kinds of reads, print(), write(),
seek(), or tell() can cause confusion because stdio usually buffers
-data. Returns the number of bytes actually read, or undef if there
-was an error. SCALAR will be grown or shrunk so that the last byte
-actually read is the last byte of the scalar after the read.
+data. Returns the number of bytes actually read, C<0> at end of file,
+or undef if there was an error. SCALAR will be grown or shrunk so that
+the last byte actually read is the last byte of the scalar after the read.
An OFFSET may be specified to place the read data at some place in the
string other than the beginning. A negative OFFSET specifies
$signal_num = $? & 127;
$dumped_core = $? & 128;
-When the arguments get executed via the system shell, results will
-be subject to its quirks and capabilities. See L<perlop/"`STRING`">
-and L</exec> for details.
+When the arguments get executed via the system shell, results
+and return codes will be subject to its quirks and capabilities.
+See L<perlop/"`STRING`"> and L</exec> for details.
=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET