X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/639bf3e507959ca53fef713306eb33f1074f1588..165b10ddfaaa8ecc72d45a9be7d29e7537dc2379:/doc/ref/posix.texi diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi index d568af23d..469c4dadb 100644 --- a/doc/ref/posix.texi +++ b/doc/ref/posix.texi @@ -1,6 +1,6 @@ @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 +@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. @@ -687,13 +687,21 @@ case @code{stat:rdev} returns @code{#f}. The size of a regular file in bytes. @end deffn @deffn {Scheme Procedure} stat:atime st -The last access time for the file. +The last access time for the file, in seconds. @end deffn @deffn {Scheme Procedure} stat:mtime st -The last modification time for the file. +The last modification time for the file, in seconds. @end deffn @deffn {Scheme Procedure} stat:ctime st -The last modification time for the attributes of the file. +The last modification time for the attributes of the file, in seconds. +@end deffn +@deffn {Scheme Procedure} stat:atimensec st +@deffnx {Scheme Procedure} stat:mtimensec st +@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 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 optimal block size for reading or writing the file, in bytes. On @@ -763,14 +771,18 @@ the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}. The return value is unspecified. @end deffn -@deffn {Scheme Procedure} utime pathname [actime [modtime]] -@deffnx {C Function} scm_utime (pathname, actime, modtime) -@cindex file times +@deffn {Scheme Procedure} utime pathname [actime [modtime [actimens [modtimens [flags]]]]] +@deffnx {C Function} scm_utime (pathname, actime, modtime, actimens, modtimens, flags) @code{utime} sets the access and modification times for the file named by @var{path}. If @var{actime} or @var{modtime} is not supplied, then the current time is used. @var{actime} and @var{modtime} must be integer time values as returned by the @code{current-time} procedure. + +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 file systems and operating +systems. @lisp (utime "foo" (- (current-time) 3600)) @end lisp @@ -936,6 +948,15 @@ which is usual for ordinary file creation, @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 @@ -1091,18 +1112,7 @@ or getgrent respectively. @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 () @@ -1596,6 +1606,12 @@ from its controlling terminal if it has one. 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 @@ -1814,6 +1830,56 @@ the highest priority (lowest numerical value) of any of the 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 @@ -2225,6 +2291,8 @@ The address of the local host using the loopback device, ie.@: @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., @@ -2235,6 +2303,8 @@ Convert an IPv4 Internet address from printable string @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., @@ -2288,8 +2358,8 @@ Convert a network address from an integer to a printable string. @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 @@ -2314,6 +2384,170 @@ This section describes procedures which query various network databases. Care should be taken when using the database routines since they are not reentrant. +@subsubheading @code{getaddrinfo} + +@cindex @code{addrinfo} object type +@cindex host name lookup +@cindex service name lookup + +The @code{getaddrinfo} procedure maps host and service names to socket addresses +and associated information in a protocol-independent way. + +@deffn {Scheme Procedure} getaddrinfo name service [hint_flags [hint_family [hint_socktype [hint_protocol]]]] +@deffnx {C Function} scm_getaddrinfo (name, service, hint_flags, hint_family, hint_socktype, hint_protocol) +Return a list of @code{addrinfo} structures containing +a socket address and associated information for host @var{name} +and/or @var{service} to be used in creating a socket with +which to address the specified service. + +@example +(let* ((ai (car (getaddrinfo "www.gnu.org" "http"))) + (s (socket (addrinfo:fam ai) (addrinfo:socktype ai) + (addrinfo:protocol ai)))) + (connect s (addrinfo:addr ai)) + s) +@end example + +When @var{service} is omitted or is @code{#f}, return +network-level addresses for @var{name}. When @var{name} +is @code{#f} @var{service} must be provided and service +locations local to the caller are returned. + +Additional hints can be provided. When specified, +@var{hint_flags} should be a bitwise-or of zero or more +constants among the following: + +@table @code +@item AI_PASSIVE +Socket address is intended for @code{bind}. + +@item AI_CANONNAME +Request for canonical host name, available via +@code{addrinfo:canonname}. This makes sense mainly when +DNS lookups are involved. + +@item AI_NUMERICHOST +Specifies that @var{name} is a numeric host address string +(e.g., @code{"127.0.0.1"}), meaning that name resolution +will not be used. + +@item AI_NUMERICSERV +Likewise, specifies that @var{service} is a numeric port +string (e.g., @code{"80"}). + +@item AI_ADDRCONFIG +Return only addresses configured on the local system It is +highly recommended to provide this flag when the returned +socket addresses are to be used to make connections; +otherwise, some of the returned addresses could be unreachable +or use a protocol that is not supported. + +@item AI_V4MAPPED +When looking up IPv6 addresses, return mapped IPv4 addresses if +there is no IPv6 address available at all. + +@item AI_ALL +If this flag is set along with @code{AI_V4MAPPED} when looking up IPv6 +addresses, return all IPv6 addresses as well as all IPv4 addresses, the latter +mapped to IPv6 format. +@end table + +When given, @var{hint_family} should specify the requested +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 interpreted +as in calls to @code{socket}). + +On error, an exception with key @code{getaddrinfo-error} is +thrown, with an error code (an integer) as its argument: + +@example +(catch 'getaddrinfo-error + (lambda () + (getaddrinfo "www.gnu.org" "gopher")) + (lambda (key errcode) + (cond ((= errcode EAI_SERVICE) + (display "doesn't know about Gopher!\n")) + ((= errcode EAI_NONAME) + (display "www.gnu.org not found\\n")) + (else + (format #t "something wrong: ~a\n" + (gai-strerror errcode)))))) +@end example + +Error codes are: + +@table @code +@item EAI_AGAIN +The name or service could not be resolved at this time. Future +attempts may succeed. + +@item EAI_BADFLAGS +@var{hint_flags} contains an invalid value. + +@item EAI_FAIL +A non-recoverable error occurred when attempting to +resolve the name. + +@item EAI_FAMILY +@var{hint_family} was not recognized. + +@item EAI_NONAME +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. + +@item EAI_SOCKTYPE +@var{hint_socktype} was not recognized. + +@item EAI_SYSTEM +A system error occurred; the error code can be found in +@code{errno}. +@end table + +Users are encouraged to read the +@url{http://www.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html, +"POSIX specification} for more details. +@end deffn + +The following procedures take an @code{addrinfo} object as returned by +@code{getaddrinfo}: + +@deffn {Scheme Procedure} addrinfo:flags ai +Return flags for @var{ai} as a bitwise or of @code{AI_} values (see above). +@end deffn + +@deffn {Scheme Procedure} addrinfo:fam ai +Return the address family of @var{ai} (a @code{AF_} value). +@end deffn + +@deffn {Scheme Procedure} addrinfo:socktype ai +Return the socket type for @var{ai} (a @code{SOCK_} value). +@end deffn + +@deffn {Scheme Procedure} addrinfo:protocol ai +Return the protocol of @var{ai}. +@end deffn + +@deffn {Scheme Procedure} addrinfo:addr ai +Return the socket address associated with @var{ai} as a @code{sockaddr} +object (@pxref{Network Socket Address}). +@end deffn + +@deffn {Scheme Procedure} addrinfo:canonname ai +Return a string for the canonical name associated with @var{ai} if +the @code{AI_CANONNAME} flag was supplied. +@end deffn + @subsubheading The Host Database @cindex @file{/etc/hosts} @cindex network database @@ -2344,7 +2578,9 @@ The list of network addresses associated with @var{host}. For Conversion}). @end deffn -The following procedures are used to search the host database: +The following procedures can be used to search the host database. However, +@code{getaddrinfo} should be preferred over them since it's more generic and +thread-safe. @deffn {Scheme Procedure} gethost [host] @deffnx {Scheme Procedure} gethostbyname hostname @@ -2627,7 +2863,7 @@ The following functions access the fields of a socket address object, @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 @@ -2815,6 +3051,16 @@ For IP level (@code{IPPROTO_IP}) the following @var{optname}s are 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}. @@ -2860,8 +3106,8 @@ same as @code{make-socket-address} would take to make such an object (@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 @@ -2876,7 +3122,7 @@ either a socket address object, or arguments the same as (@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. @@ -2931,7 +3177,7 @@ Note that on many systems the address of a socket in the @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. @@ -2942,7 +3188,7 @@ Note that on many systems the address of a socket in the 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 @@ -2969,7 +3215,7 @@ any unread buffered port data is ignored. @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 @@ -2981,17 +3227,18 @@ file descriptor: 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 @@ -3021,7 +3268,7 @@ application may need to use @code{select}, @code{O_NONBLOCK} or @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 @@ -3107,7 +3354,7 @@ returns the contents of the root index URL. @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))) @@ -3128,7 +3375,7 @@ client. (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)