@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@deffnx {Scheme Procedure} stat:ctimensec st
The fractional part of a file's access, modification, or attribute modification
time, in nanoseconds. Nanosecond timestamps are only available on some operating
-systems and filesystems. If Guile cannot retrieve nanosecond-level timestamps
+systems and file systems. If Guile cannot retrieve nanosecond-level timestamps
for a file, these fields will be set to 0.
@end deffn
@deffn {Scheme Procedure} stat:blksize st
The optional @var{actimens} and @var{modtimens} are nanoseconds
to add @var{actime} and @var{modtime}. Nanosecond precision is
-only supported on some combinations of filesystems and operating
+only supported on some combinations of file systems and operating
systems.
@lisp
(utime "foo" (- (current-time) 3600))
@end example
@end deffn
+@deffn {Scheme Procedure} tmpfile
+@deffnx {C Function} scm_tmpfile
+Return an input/output port to a unique temporary file
+named using the path prefix @code{P_tmpdir} defined in
+@file{stdio.h}.
+The file is automatically deleted when the port is closed
+or the program terminates.
+@end deffn
+
@deffn {Scheme Procedure} dirname filename
@deffnx {C Function} scm_dirname (filename)
Return the directory name component of the file name
@end deffn
In addition to the accessor procedures for the user database, the
-following shortcut procedures are also available.
-
-@deffn {Scheme Procedure} cuserid
-@deffnx {C Function} scm_cuserid ()
-Return a string containing a user name associated with the
-effective user id of the process. Return @code{#f} if this
-information cannot be obtained.
-
-This function has been removed from the latest POSIX specification,
-Guile provides it only if the system has it. Using @code{(getpwuid
-(geteuid))} may be a better idea.
-@end deffn
+following shortcut procedure is also available.
@deffn {Scheme Procedure} getlogin
@deffnx {C Function} scm_getlogin ()
specified processes.
@end deffn
+@cindex affinity, CPU
+
+@deffn {Scheme Procedure} getaffinity pid
+@deffnx {C Function} scm_getaffinity (pid)
+Return a bitvector representing the CPU affinity mask for
+process @var{pid}. Each CPU the process has affinity with
+has its corresponding bit set in the returned bitvector.
+The number of bits set is a good estimate of how many CPUs
+Guile can use without stepping on other processes' toes.
+
+Currently this procedure is only defined on GNU variants
+(@pxref{CPU Affinity, @code{sched_getaffinity},, libc, The
+GNU C Library Reference Manual}).
+@end deffn
+
+@deffn {Scheme Procedure} setaffinity pid mask
+@deffnx {C Function} scm_setaffinity (pid, mask)
+Install the CPU affinity mask @var{mask}, a bitvector, for
+the process or thread with ID @var{pid}. The return value
+is unspecified.
+
+Currently this procedure is only defined on GNU variants
+(@pxref{CPU Affinity, @code{sched_setaffinity},, libc, The
+GNU C Library Reference Manual}).
+@end deffn
+
+@deffn {Scheme Procedure} total-processor-count
+@deffnx {C Function} scm_total_processor_count ()
+Return the total number of processors of the machine, which
+is guaranteed to be at least 1. A ``processor'' here is a
+thread execution unit, which can be either:
+
+@itemize
+@item an execution core in a (possibly multi-core) chip, in a
+ (possibly multi- chip) module, in a single computer, or
+@item a thread execution unit inside a core in the case of
+ @dfn{hyper-threaded} CPUs.
+@end itemize
+
+Which of the two definitions is used, is unspecified.
+@end deffn
+
+@deffn {Scheme Procedure} current-processor-count
+@deffnx {C Function} scm_current_processor_count ()
+Like @code{total-processor-count}, but return the number of
+processors available to the current process. See
+@code{setaffinity} and @code{getaffinity} for more
+information.
+@end deffn
+
@node Signals
@subsection Signals
@example
(let* ((ai (car (getaddrinfo "www.gnu.org" "http")))
(s (socket (addrinfo:fam ai) (addrinfo:socktype ai)
- (addrinfo:protocol ai))))
+ (addrinfo:protocol ai))))
(connect s (addrinfo:addr ai))
s)
@end example
address family, e.g., @code{AF_INET6}. Similarly,
@var{hint_socktype} should specify the requested socket type
(e.g., @code{SOCK_DGRAM}), and @var{hint_protocol} should
-specify the requested protocol (its value is interpretered
+specify the requested protocol (its value is interpreted
as in calls to @code{socket}).
On error, an exception with key @code{getaddrinfo-error} is
Either @var{name} does not resolve for the supplied parameters,
or neither @var{name} nor @var{service} were supplied.
+@item EAI_NODATA
+This non-POSIX error code can be returned on GNU systems when a
+request was actually made but returned no data, meaning
+that no address is associated with @var{name}. Error handling
+code should be prepared to handle it when it is defined.
+
@item EAI_SERVICE
@var{service} was not recognized for the specified socket type.
@deffn {Scheme Procedure} sockaddr:fam sa
Return the address family from socket address object @var{sa}. This
-is one of the @code{AF} constants (eg. @code{AF_INET}).
+is one of the @code{AF} constants (e.g.@: @code{AF_INET}).
@end deffn
@deffn {Scheme Procedure} sockaddr:path sa
defined (when provided by the system). See @command{man ip} for what
they mean.
+@defvar IP_MULTICAST_IF
+This sets the source interface used by multicast traffic.
+@end defvar
+
+@defvar IP_MULTICAST_TTL
+This sets the default TTL for multicast traffic. This defaults
+to 1 and should be increased to allow traffic to pass beyond the
+local network.
+@end defvar
+
@defvar IP_ADD_MEMBERSHIP
@defvarx IP_DROP_MEMBERSHIP
These can be used only with @code{setsockopt}, not @code{getsockopt}.
(@pxref{Network Socket Address}). The return value is unspecified.
Generally a socket is only explicitly bound to a particular address
-when making a server, ie. to listen on a particular port. For an
+when making a server, i.e.@: to listen on a particular port. For an
outgoing connection the system will assign a local address
automatically, if not already bound.
@deffn {Scheme Procedure} getpeername sock
@deffnx {C Function} scm_getpeername (sock)
Return a socket address object which is where @var{sock} is connected
-to, ie. the remote endpoint.
+to, i.e.@: the remote endpoint.
Note that on many systems the address of a socket in the
@code{AF_UNIX} namespace cannot be read.
Receive data from a socket port.
@var{sock} must already
be bound to the address from which data is to be received.
-@var{buf} is a string into which
+@var{buf} is a bytevector into which
the data will be written. The size of @var{buf} limits
the amount of
data which can be received: in the case of packet
@vindex MSG_OOB
@vindex MSG_PEEK
@vindex MSG_DONTROUTE
-Transmit the string @var{message} on a socket port @var{sock}.
+Transmit bytevector @var{message} on socket port @var{sock}.
@var{sock} must already be bound to a destination address. The value
returned is the number of bytes transmitted---it's possible for this
to be less than the length of @var{message} if the socket is set to be
any unflushed buffered port data is ignored.
@end deffn
-@deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
-@deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
+@deffn {Scheme Procedure} recvfrom! sock buf [flags [start [end]]]
+@deffnx {C Function} scm_recvfrom (sock, buf, flags, start, end)
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 data received is stored in bytevector @var{buf}, using
+either the whole bytevector or just the region between the optional
+@var{start} and @var{end} positions. The size of @var{buf}
+limits the amount of data that 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
@deffnx {Scheme Procedure} sendto sock message AF_INET6 ipv6addr port [flowinfo [scopeid [flags]]]
@deffnx {Scheme Procedure} sendto sock message AF_UNIX path [flags]
@deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
-Transmit the string @var{message} as a datagram on socket port
+Transmit bytevector @var{message} as a datagram socket port
@var{sock}. The destination is specified either as a socket address
object, or as arguments the same as would be taken by
@code{make-socket-address} to create such an object (@pxref{Network
HCoop / bpt / guile.git / blobdiff