@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@end defvar
@end deffn
-@deffn {Scheme Procedure} fcntl object cmd [value]
+@deffn {Scheme Procedure} fcntl port/fd cmd [value]
@deffnx {C Function} scm_fcntl (object, cmd, value)
-Apply @var{cmd} on @var{object}, either a port or file descriptor.
-The @var{value} is an integer argument, for the @code{SET} commands.
+Apply @var{cmd} on @var{port/fd}, either a port or file descriptor.
+The @var{value} argument is used by the @code{SET} commands described
+below, it's an integer value.
Values for @var{cmd} are:
@example
(fcntl port F_SETFD FD_CLOEXEC)
@end example
+
+Or better, set it but leave any other possible future flags unchanged,
+
+@example
+(fcntl port F_SETFD (logior FD_CLOEXEC
+ (fcntl port F_GETFD)))
+@end example
@end defvar
@end defvar
following sets that flag, and leaves other flags unchanged.
@example
-(fcntl sock F_SETFL
- (logior (fcntl sock F_GETFL) O_NONBLOCK))
+(fcntl sock F_SETFL (logior O_NONBLOCK
+ (fcntl sock F_GETFL)))
@end example
@end defvar
@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
@end deffn
@deffn {Scheme Procedure} getpwent
-Return the next entry in the user database, using the stream set by
-@code{setpwent}.
+Read the next entry in the user database stream. The return is a
+passwd user object as above, or @code{#f} when no more entries.
@end deffn
@deffn {Scheme Procedure} endpwent
@deffn {Scheme Procedure} tm:gmtoff tm
@deffnx {Scheme Procedure} set-tm:gmtoff tm val
Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
+For example on East coast USA (zone @samp{EST+5}) this would be 18000
+(ie.@: @m{5\times60\times60,5*60*60}) in winter, or 14400
+(ie.@: @m{4\times60\times60,4*60*60}) during daylight savings.
+
+Note @code{tm:gmtoff} is not the same as @code{tm_gmtoff} in the C
+@code{tm} structure. @code{tm_gmtoff} is seconds east and hence the
+negative of the value here.
@end deffn
@deffn {Scheme Procedure} tm:zone tm
@deffnx {Scheme Procedure} set-tm:zone tm val
@deffn {Scheme Procedure} program-arguments
@deffnx {Scheme Procedure} command-line
+@deffnx {Scheme Procedure} set-program-arguments
@deffnx {C Function} scm_program_arguments ()
+@deffnx {C Function} scm_set_program_arguments_scm (lst)
@cindex command line
@cindex program arguments
-Return the list of command line arguments passed to Guile, as a list of
-strings. The list includes the invoked program name, which is usually
-@code{"guile"}, but excludes switches and parameters for command line
-options like @code{-e} and @code{-l}.
+Get the command line arguments passed to Guile, or set new arguments.
+
+The arguments are a list of strings, the first of which is the invoked
+program name. This is just @nicode{"guile"} (or the executable path)
+when run interactively, or it's the script name when running a script
+with @option{-s} (@pxref{Invoking Guile}).
+
+@example
+guile -L /my/extra/dir -s foo.scm abc def
+
+(program-arguments) @result{} ("foo.scm" "abc" "def")
+@end example
+
+@code{set-program-arguments} allows a library module or similar to
+modify the arguments, for example to strip options it recognises,
+leaving the rest for the mainline.
+
+The argument list is held in a fluid, which means it's separate for
+each thread. Neither the list nor the strings within it are copied at
+any point and normally should not be mutated.
+
+The two names @code{program-arguments} and @code{command-line} are an
+historical accident, they both do exactly the same thing. The name
+@code{scm_set_program_arguments_scm} has an extra @code{_scm} on the
+end to avoid clashing with the C function below.
@end deffn
+@deftypefn {C Function} void scm_set_program_arguments (int argc, char **argv, char *first)
+@cindex command line
+@cindex program arguments
+Set the list of command line arguments for @code{program-arguments}
+and @code{command-line} above.
+
+@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} 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];
+ for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++)
+ @{
+ /* munch option ... */
+ @}
+ /* remaining args for scheme level use */
+ scm_set_program_arguments (-1, argv, progname);
+@}
+@end example
+
+This sort of thing is often done at startup under
+@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
+
@deffn {Scheme Procedure} getenv nam
@deffnx {C Function} scm_getenv (nam)
@cindex environment
@end deffn
@deffn {Scheme Procedure} primitive-exit [status]
+@deffnx {Scheme Procedure} primitive-_exit [status]
@deffnx {C Function} scm_primitive_exit (status)
-Terminate the current process without unwinding the Scheme stack.
-This is would typically be useful after a fork. The exit status
-is @var{status} if supplied, otherwise zero.
+@deffnx {C Function} scm_primitive__exit (status)
+Terminate the current process without unwinding the Scheme stack. The
+exit status is @var{status} if supplied, otherwise zero.
+
+@code{primitive-exit} uses the C @code{exit} function and hence runs
+usual C level cleanups (flush output streams, call @code{atexit}
+functions, etc, see @ref{Normal Termination,,, libc, The GNU C Library
+Reference Manual})).
+
+@code{primitive-_exit} is the @code{_exit} system call
+(@pxref{Termination Internals,,, libc, The GNU C Library Reference
+Manual}). This terminates the program immediately, with neither
+Scheme-level nor C-level cleanups.
+
+The typical use for @code{primitive-_exit} is from a child process
+created with @code{primitive-fork}. For example in a Gdk program the
+child process inherits the X server connection and a C-level
+@code{atexit} cleanup which will close that connection. But closing
+in the child would upset the protocol in the parent, so
+@code{primitive-_exit} should be used to exit without that.
@end deffn
@deffn {Scheme Procedure} execl filename . args
@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)
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} 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.
+@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.
-Return information about the timer's previous setting.
+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.
-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
@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
@deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
@deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
-Return data from the socket port @var{sock} and also
-information about where the data was received from.
-@var{sock} must already be bound to the address from which
-data is to be received. @code{str}, is a string into which the
-data will be written. The size of @var{str} limits the amount
-of data which can be received: in the case of packet protocols,
-if a packet larger than this limit is encountered then some
-data will be irrevocably lost.
+Receive data from socket port @var{sock}, returning the originating
+address as well as the data. This function is usually for datagram
+sockets, but can be used on stream-oriented sockets too.
+
+The data received is stored in the given @var{str}, the whole string
+or just the region between the optional @var{start} and @var{end}
+positions. The size of @var{str} limits the amount of data which can
+be received. For datagram protocols if a packet larger than this is
+received then excess bytes are irrevocably lost.
+
+The return value is a pair. The @code{car} is the number of bytes
+read. The @code{cdr} is a socket address object (@pxref{Network
+Socket Address}) which is where the data came from, or @code{#f} if
+the origin is unknown.
@vindex MSG_OOB
@vindex MSG_PEEK
@vindex MSG_DONTROUTE
-The optional @var{flags} argument is a value or bitwise OR of
-@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
-
-The value returned is a pair: the @acronym{CAR} is the number of
-bytes read from the socket and the @acronym{CDR} an address object
-in the same form as returned by @code{accept}. The address
-will given as @code{#f} if not available, as is usually the
-case for stream sockets.
+The optional @var{flags} argument is a or bitwise-OR (@code{logior})
+of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
-The @var{start} and @var{end} arguments specify a substring of
-@var{str} to which the data should be written.
+Data is read directly from the socket file descriptor, any buffered
+port data is ignored.
-Note that the data is read directly from the socket file
-descriptor: any unread buffered port data is ignored.
+@c This was linux kernel 2.6.15 and glibc 2.3.6, not sure what any
+@c specs are supposed to say about recvfrom threading.
+@c
+On a GNU/Linux system @code{recvfrom!} is not multi-threading, all
+threads stop while a @code{recvfrom!} call is in progress. An
+application may need to use @code{select}, @code{O_NONBLOCK} or
+@code{MSG_DONTWAIT} to avoid this.
@end deffn
@deffn {Scheme Procedure} sendto sock message sockaddr [flags]
Get or set the current locale, used for various internationalizations.
Locales are strings, such as @samp{sv_SE}.
-If @var{locale} is given then the locale for the given @var{category} is set
-and the new value returned. If @var{locale} is not given then the
-current value is returned. @var{category} should be one of the
-following values
+If @var{locale} is given then the locale for the given @var{category}
+is set and the new value returned. If @var{locale} is not given then
+the current value is returned. @var{category} should be one of the
+following values (@pxref{Locale Categories, Categories of Activities
+that Locales Affect,, libc, The GNU C Library Reference Manual}):
@defvar LC_ALL
@defvarx LC_COLLATE
For full details on categories and locale names @pxref{Locales,,
Locales and Internationalization, libc, The GNU C Library Reference
Manual}.
+
+Note that @code{setlocale} affects locale settings for the whole
+process. @xref{i18n Introduction, locale objects and
+@code{make-locale}}, for a thread-safe alternative.
@end deffn
@node Encryption
strong encryption, they are only interfaces to the well-known and
common system library functions of the same name. They are just as good
(or bad) as the underlying functions, so you should refer to your system
-documentation before using them.
+documentation before using them (@pxref{crypt,, Encrypting Passwords,
+libc, The GNU C Library Reference Manual}).
@deffn {Scheme Procedure} crypt key salt
@deffnx {C Function} scm_crypt (key, salt)
-Encrypt @var{key} using @var{salt} as the salt value to the
-crypt(3) library call.
+Encrypt @var{key}, with the addition of @var{salt} (both strings),
+using the @code{crypt} C library call.
@end deffn
Although @code{getpass} is not an encryption procedure per se, it
HCoop / bpt / guile.git / blobdiff