@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007,
-@c 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
+@c 2008, 2009, 2010, 2011, 2012, 2013, 2014 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node POSIX
to provide input, accept output, or the existence of
exceptional conditions on a collection of ports or file
descriptors, or waiting for a timeout to occur.
-It also returns if interrupted by a signal.
+
+When an error occurs, of if it is interrupted by a signal, this
+procedure throws a @code{system-error} exception
+(@pxref{Conventions, @code{system-error}}). In case of an
+interruption, the associated error number is @var{EINTR}.
@var{reads}, @var{writes} and @var{excepts} can be lists or
vectors, with each member a port or a file descriptor.
Terminate the current process with proper unwinding of the Scheme stack.
The exit status zero if @var{status} is not supplied. If @var{status}
is supplied, and it is an integer, that integer is used as the exit
-status. If @var{status} is @code{#t} or @code{#f}, the exit status is 0
-or 1, respectively.
+status. If @var{status} is @code{#t} or @code{#f}, the exit status is
+@var{EXIT_SUCCESS} or @var{EXIT_FAILURE}, respectively.
The procedure @code{exit} is an alias of @code{quit}. They have the
same functionality.
@end deffn
+@defvr {Scheme Variable} EXIT_SUCCESS
+@defvrx {Scheme Variable} EXIT_FAILURE
+These constants represent the standard exit codes for success (zero) or
+failure (one.)
+@end defvr
+
@deffn {Scheme Procedure} primitive-exit [status]
@deffnx {Scheme Procedure} primitive-_exit [status]
@deffnx {C Function} scm_primitive_exit (status)
@end deffn
@deffn {Scheme Procedure} getitimer which_timer
-@deffnx {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds periodic_seconds periodic_microseconds
+@deffnx {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
@deffnx {C Function} scm_getitimer (which_timer)
-@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, periodic_seconds, periodic_microseconds)
-Get or set the periods programmed in certain system timers. These
-timers have a current interval value which counts down and on reaching
-zero raises a signal. An optional periodic value can be set to
-restart from there each time, for periodic operation.
-@var{which_timer} is one of the following values
+@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
+Get or set the periods programmed in certain system timers.
+
+These timers have two settings. The first setting, the interval, is the
+value at which the timer will be reset when the current timer expires.
+The second is the current value of the timer, indicating when the next
+expiry will be signalled.
+
+@var{which_timer} is one of the following values:
@defvar ITIMER_REAL
A real-time timer, counting down elapsed real time. At zero it raises
time (by looking where it is when the timer goes off).
@end defvar
-@code{getitimer} returns the current timer value and its programmed
-restart value, as a list containing two pairs. Each pair is a time in
-seconds and microseconds: @code{((@var{interval_secs}
-. @var{interval_usecs}) (@var{periodic_secs}
-. @var{periodic_usecs}))}.
+@code{getitimer} returns the restart timer value and its current value,
+as a list containing two pairs. Each pair is a time in seconds and
+microseconds: @code{((@var{interval_secs} . @var{interval_usecs})
+(@var{value_secs} . @var{value_usecs}))}.
@code{setitimer} sets the timer values similarly, in seconds and
-microseconds (which must be integers). The periodic value can be zero
+microseconds (which must be integers). The interval value can be zero
to have the timer run down just once. The return value is the timer's
previous setting, in the same form as @code{getitimer} returns.
@example
(setitimer ITIMER_REAL
- 5 500000 ;; first SIGALRM in 5.5 seconds time
- 2 0) ;; then repeat every 2 seconds
+ 5 500000 ;; Raise SIGALRM every 5.5 seconds
+ 2 0) ;; with the first SIGALRM in 2 seconds
@end example
Although the timers are programmed in microseconds, the actual
any unflushed buffered port data is ignored.
@end deffn
-The following functions can be used to convert short and long integers
-between ``host'' and ``network'' order. Although the procedures above do
-this automatically for addresses, the conversion will still need to
-be done when sending or receiving encoded integer data from the network.
-
-@deffn {Scheme Procedure} htons value
-@deffnx {C Function} scm_htons (value)
-Convert a 16 bit quantity from host to network byte ordering.
-@var{value} is packed into 2 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} ntohs value
-@deffnx {C Function} scm_ntohs (value)
-Convert a 16 bit quantity from network to host byte ordering.
-@var{value} is packed into 2 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} htonl value
-@deffnx {C Function} scm_htonl (value)
-Convert a 32 bit quantity from host to network byte ordering.
-@var{value} is packed into 4 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-@deffn {Scheme Procedure} ntohl value
-@deffnx {C Function} scm_ntohl (value)
-Convert a 32 bit quantity from network to host byte ordering.
-@var{value} is packed into 4 bytes, which are then converted
-and returned as a new integer.
-@end deffn
-
-These procedures are inconvenient to use at present, but consider:
-
-@example
-(define write-network-long
- (lambda (value port)
- (let ((v (make-uniform-vector 1 1 0)))
- (uniform-vector-set! v 0 (htonl value))
- (uniform-vector-write v port))))
-
-(define read-network-long
- (lambda (port)
- (let ((v (make-uniform-vector 1 1 0)))
- (uniform-vector-read! v port)
- (ntohl (uniform-vector-ref v 0)))))
-@end example
-
@node Internet Socket Examples
@subsubsection Network Socket Examples
HCoop / bpt / guile.git / blobdiff