@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 Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@end lisp
@end deffn
+@deffn {Scheme Procedure} file-exists? filename
+Return @code{#t} if the file named @var{filename} exists, @code{#f} if
+not.
+@end deffn
+
@node User Information
@subsection User Information
If @code{setlocale} has been called (@pxref{Locales}), month and day
names are from the current locale and in the locale character set.
-
-Note that @samp{%Z} might print the @code{tm:zone} in @var{tm} or it
-might print just the current zone (@code{tzset} above). A GNU system
-prints @code{tm:zone}, a strict C99 system like NetBSD prints the
-current zone. Perhaps in the future Guile will try to get
-@code{tm:zone} used always.
-@c
-@c The issue in the above is not just whether tm_zone exists in
-@c struct tm, but whether libc feels it should read it. Being a
-@c non-C99 field, a strict C99 program won't know to set it, quite
-@c likely leaving garbage there. NetBSD, which has the field,
-@c therefore takes the view that it mustn't read it. See the PR
-@c about this at
-@c
-@c http://www.netbsd.org/cgi-bin/query-pr-single.pl?number=21722
-@c
-@c Uniformly making tm:zone used on all systems (all those which have
-@c %Z at all of course) might be nice (either mung TZ and tzset, or
-@c mung tzname[]). On the other hand it would make us do more than
-@c C99 says, and we really don't want to get intimate with the gory
-@c details of libc time funcs, no more than can be helped.
-@c
@end deffn
@deffn {Scheme Procedure} strptime format string
@var{argv} is an array of null-terminated strings, as in a C
@code{main} function. @var{argc} is the number of strings in
-@var{argv}, or if it's negative then a @code{NULL} entry in @var{argv}
-marks its end.
+@var{argv}, or if it's negative then a @code{NULL} in @var{argv} marks
+its end.
@var{first} is an extra string put at the start of the arguments, or
@code{NULL} for no such extra. This is a convenient way to pass the
program name after advancing @var{argv} to strip option arguments.
+Eg.@:
@example
@{
char *progname = argv[0];
- int i;
for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++)
@{
/* munch option ... */
@end example
This sort of thing is often done at startup under
-@code{scm_boot_guile} with any options handled at the C level removed.
+@code{scm_boot_guile} with options handled at the C level removed.
The given strings are all copied, so the C data is not accessed again
once @code{scm_set_program_arguments} returns.
@end deftypefn
The return value is an integer representing the new process group ID.
@end deffn
+@deffn {Scheme Procedure} getsid pid
+@deffnx {C Function} scm_getsid (pid)
+Returns the session ID of process @var{pid}. (The session
+ID of a process is the process group ID of its session leader.)
+@end deffn
+
@deffn {Scheme Procedure} waitpid pid [options]
@deffnx {C Function} scm_waitpid (pid, options)
This procedure collects status information from a child process which
@subsection Signals
@cindex signal
-Procedures to raise, handle and wait for signals.
+The following procedures raise, handle and wait for signals.
+
+Scheme code signal handlers are run via a system async (@pxref{System
+asyncs}), so they're called in the handler's thread at the next safe
+opportunity. Generally this is after any currently executing
+primitive procedure finishes (which could be a long time for
+primitives that wait for an external event).
@deffn {Scheme Procedure} kill pid sig
@deffnx {C Function} scm_kill (pid, sig)
If a signal occurs while in a system call, deliver the signal then
restart the system call (as opposed to returning an @code{EINTR} error
from that call).
-
-Guile always enables this flag where available, no matter what
-@var{flags} are specified. This avoids spurious error returns in low
-level operations.
@end defvar
The return value is a pair with information about the old handler as
handler procedure. The return value is unspecified.
@end deffn
-@deffn {Scheme Procedure} sleep i
-@deffnx {C Function} scm_sleep (i)
-Wait for the given number of seconds (an integer) or until a signal
-arrives. The return value is zero if the time elapses or the number
-of seconds remaining otherwise.
-@end deffn
-
-@deffn {Scheme Procedure} usleep i
-@deffnx {C Function} scm_usleep (i)
-Sleep for @var{i} microseconds. @code{usleep} is not available on
-all platforms. [FIXME: so what happens when it isn't?]
-@end deffn
+@deffn {Scheme Procedure} sleep secs
+@deffnx {Scheme Procedure} usleep usecs
+@deffnx {C Function} scm_sleep (secs)
+@deffnx {C Function} scm_usleep (usecs)
+Wait the given period @var{secs} seconds or @var{usecs} microseconds
+(both integers). If a signal arrives the wait stops and the return
+value is the time remaining, in seconds or microseconds respectively.
+If the period elapses with no signal the return is zero.
-@deffn {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds value_seconds value_microseconds
-@deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, value_seconds, value_microseconds)
-Set the timer specified by @var{which_timer} according to the given
-@var{interval_seconds}, @var{interval_microseconds},
-@var{value_seconds}, and @var{value_microseconds} values.
+On most systems the process scheduler is not microsecond accurate and
+the actual period slept by @code{usleep} might be rounded to a system
+clock tick boundary, which might be 10 milliseconds for instance.
-Return information about the timer's previous setting.
-
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
-
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
+See @code{scm_std_sleep} and @code{scm_std_usleep} for equivalents at
+the C level (@pxref{Blocking}).
@end deffn
@deffn {Scheme Procedure} getitimer which_timer
+@deffnx {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds periodic_seconds periodic_microseconds
@deffnx {C Function} scm_getitimer (which_timer)
-Return information about the timer specified by @var{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
+
+@defvar ITIMER_REAL
+A real-time timer, counting down elapsed real time. At zero it raises
+@code{SIGALRM}. This is like @code{alarm} above, but with a higher
+resolution period.
+@end defvar
+
+@defvar ITIMER_VIRTUAL
+A virtual-time timer, counting down while the current process is
+actually using CPU. At zero it raises @code{SIGVTALRM}.
+@end defvar
+
+@defvar ITIMER_PROF
+A profiling timer, counting down while the process is running (like
+@code{ITIMER_VIRTUAL}) and also while system calls are running on the
+process's behalf. At zero it raises a @code{SIGPROF}.
+
+This timer is intended for profiling where a program is spending its
+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{setitimer} sets the timer values similarly, in seconds and
+microseconds (which must be integers). The periodic 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.
-The timers available are: @code{ITIMER_REAL}, @code{ITIMER_VIRTUAL},
-and @code{ITIMER_PROF}.
+@example
+(setitimer ITIMER_REAL
+ 5 500000 ;; first SIGALRM in 5.5 seconds time
+ 2 0) ;; then repeat every 2 seconds
+@end example
-The return value will be a list of two cons pairs representing the
-current state of the given timer. The first pair is the seconds and
-microseconds of the timer @code{it_interval}, and the second pair is
-the seconds and microseconds of the timer @code{it_value}.
+Although the timers are programmed in microseconds, the actual
+accuracy might not be that high.
@end deffn
@code{pclose} system routines. The code is in a separate ``popen''
module:
-@smalllisp
+@lisp
(use-modules (ice-9 popen))
-@end smalllisp
+@end lisp
@findex popen
@deffn {Scheme Procedure} open-pipe command mode
@deffn {Scheme Procedure} inet-aton address
@deffnx {C Function} scm_inet_aton (address)
+This function is deprecated in favor of @code{inet-pton}.
+
Convert an IPv4 Internet address from printable string
(dotted decimal notation) to an integer. E.g.,
@deffn {Scheme Procedure} inet-ntoa inetid
@deffnx {C Function} scm_inet_ntoa (inetid)
+This function is deprecated in favor of @code{inet-ntop}.
+
Convert an IPv4 Internet address to a printable
(dotted decimal notation) string. E.g.,
@lisp
(inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
-(inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
-ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
+(inet-ntop AF_INET6 (- (expt 2 128) 1))
+ @result{} "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
@end lisp
@end deffn
(@pxref{Network Socket Address}). The return value is unspecified.
@example
-(connect sock AF_INET INADDR_LOCALHOST 23)
-(connect sock (make-socket-address AF_INET INADDR_LOCALHOST 23))
+(connect sock AF_INET INADDR_LOOPBACK 23)
+(connect sock (make-socket-address AF_INET INADDR_LOOPBACK 23))
@end example
@end deffn
@example
(bind sock AF_INET INADDR_ANY 12345)
-(bind sock (make-socket-object AF_INET INADDR_ANY 12345))
+(bind sock (make-socket-address AF_INET INADDR_ANY 12345))
@end example
@end deffn
@example
(let ((s (socket PF_INET SOCK_STREAM 0)))
- (connect s AF_INET (inet-aton "127.0.0.1") 80)
+ (connect s AF_INET (inet-pton AF_INET "127.0.0.1") 80)
(display "GET / HTTP/1.0\r\n\r\n" s)
(do ((line (read-line s) (read-line s)))
(let ((s (socket PF_INET SOCK_STREAM 0)))
(setsockopt s SOL_SOCKET SO_REUSEADDR 1)
;; @r{Specific address?}
- ;; @r{(bind s AF_INET (inet-aton "127.0.0.1") 2904)}
+ ;; @r{(bind s AF_INET (inet-pton AF_INET "127.0.0.1") 2904)}
(bind s AF_INET INADDR_ANY 2904)
(listen s 5)
Manual}.
Note that @code{setlocale} affects locale settings for the whole
-process. @xref{The ice-9 i18n Module, locale objects and
+process. @xref{i18n Introduction, locale objects and
@code{make-locale}}, for a thread-safe alternative.
@end deffn
HCoop / bpt / guile.git / blobdiff