PageRenderTime 14ms CodeModel.GetById 3ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 1ms

/doc/srfi-basic-socket-interface.texi

http://github.com/marcomaggi/vicare
Unknown | 741 lines | 549 code | 192 blank | 0 comment | 0 complexity | 52ac820360d32cc3b128927a9488c664 MD5 | raw file
  1@node srfi basic-socket
  2@section @ansrfi{106} basic socket interface
  3
  4
  5@cindex @ansrfi{106} basic socket interface
  6@cindex @library{srfi :106}, library
  7@cindex @library{srfi :106 socket}, library
  8@cindex Library @library{srfi :106}
  9@cindex Library @library{srfi :106 socket}
 10
 11
 12The library @library{srfi :106} is by Takashi Kato as the reference
 13implementation for @ansrfi{106}; see:
 14
 15@center @url{http://srfi.schemers.org/srfi-106/srfi-106.html}
 16
 17@noindent
 18for more details.
 19
 20@menu
 21* srfi basic-socket abstract::  Abstract.
 22* srfi basic-socket rationale:: Rationale.
 23* srfi basic-socket spec::      Specification.
 24* srfi basic-socket examples::  Examples.
 25* srfi basic-socket refs::      References.
 26* srfi basic-socket copyright:: Copyright.
 27@end menu
 28
 29@c page
 30@node srfi basic-socket abstract
 31@subsection Abstract
 32
 33
 34This document specifies basic socket interfaces.
 35
 36@c page
 37@node srfi basic-socket rationale
 38@subsection Rationale
 39
 40
 41Many Scheme implementations have their own socket @api{}s however there
 42are no portable way to write socket programs.  Therefore programmers
 43need to provide implementation dependent layers for their programs.
 44
 45This document specifies high and middle range of socket interfaces which
 46are commonly used for socket programming.  It should make it easier to
 47write portable programs that need to send or receive data from their
 48socket.
 49
 50@c page
 51@node srfi basic-socket spec
 52@subsection Specification
 53
 54
 55@menu
 56* srfi basic-socket spec intro::        Introduction.
 57* srfi basic-socket spec cons::         Constructors and predicates.
 58* srfi basic-socket spec ops::          Socket operations.
 59* srfi basic-socket spec port::         Port conversion.
 60* srfi basic-socket spec control::      Control features.
 61* srfi basic-socket spec flag::         Flag operations.
 62* srfi basic-socket spec const::        Constants.
 63@end menu
 64
 65@c page
 66@node srfi basic-socket spec intro
 67@subsubsection Introduction
 68
 69
 70All procedures defined in this @srfi{} may raise an error when the
 71procedure fails because of a connection problem or other socket related
 72problems.  This document does not specify which condition should be
 73raised.
 74
 75Names defined in this document:
 76
 77@table @strong
 78@item Constructors and predicates
 79@example
 80make-client-socket              make-server-socket
 81socket?
 82@end example
 83
 84@item Socket operations
 85@example
 86socket-accept
 87socket-send                     socket-recv
 88socket-shutdown                 socket-close
 89@end example
 90
 91@item Port conversion
 92@example
 93socket-input-port
 94socket-output-port
 95@end example
 96
 97@item Control feature
 98@example
 99call-with-socket
100@end example
101
102@item Flag operations
103@example
104address-family                  address-info
105socket-domain                   ip-protocol
106message-type                    shutdown-method
107socket-merge-flags              socket-purge-flags
108@end example
109
110@item Constant values
111@example
112*af-unspec*             *af-inet*               *af-inet6*
113*sock-stream            *sock-dgram*
114*ai-canonname*          *ai-numerichost*
115*ai-v4mapped*           *ai-all*                *ai-addrconfig*
116*ipproto-ip*            *ipproto-tcp*           *ipproto-udp*
117*msg-peek*              *msg-oob*               *msg-waitall*
118*shut-rd*               *shut-wr*               *shut-rdwr*
119@end example
120@end table
121
122The procedure description uses following notation:
123
124@table @var
125@item socket
126A socket object.
127
128@item bv
129A bytevector.
130
131@item obj
132Any value.
133@end table
134
135@c page
136@node srfi basic-socket spec cons
137@subsubsection Constructors and predicates
138
139
140The following bindings are exported by the libraries @library{srfi :106}
141and @library{srfi :106 socket}.
142
143
144@defun make-client-socket @var{node} @var{service}
145@defunx make-client-socket @var{node} @var{service} @var{ai-family}
146@defunx make-client-socket @var{node} @var{service} @var{ai-family} @var{ai-socktype}
147@defunx make-client-socket @var{node} @var{service} @var{ai-family} @var{ai-socktype} @var{ai-flags}
148@defunx make-client-socket @var{node} @var{service} @var{ai-family} @var{ai-socktype} @var{ai-flags} @var{ai-protocol}
149Return a client socket connected to an Internet address.
150
151The Internet address is identified by @var{node} and @var{service}.
152@var{node} and @var{service} must be strings.  Example values for
153@var{node}: @samp{"localhost"}, @samp{127.0.0.1}.  Example values for
154@var{service}: @samp{"http"}, @samp{"80"}.
155
156The optional arguments may specify the created socket's behaviour.  If
157the optional arguments are omitted, then the following value should be
158used as default:
159
160@table @var
161@item ai-family
162Defaults to: @code{*af-inet*}.
163
164@item ai-socktype
165Defaults to: @code{*sock-stream*}.
166
167@item ai-flags
168Defaults to: @code{(socket-merge-flags *ai-v4mapped* *ai-addrconfig*)}.
169
170@item ai-protocol
171Defaults to: @code{*ipproto-ip*}.
172@end table
173
174The returned socket may not be closed automatically so it is the users'
175responsibility to close it explicitly.
176
177@quotation
178@strong{For Vicare:} whenever the returned socket object is garbage
179collected, the function @func{socket-close} is automatically applied to
180it.
181@end quotation
182@end defun
183
184
185@defun make-server-socket @var{service}
186@defunx make-server-socket @var{service} @var{ai-family}
187@defunx make-server-socket @var{service} @var{ai-family} @var{ai-socktype}
188@defunx make-server-socket @var{service} @var{ai-family} @var{ai-socktype} @var{ai-protocol}
189Return a server socket waiting for connection.
190
191The @var{node} argument is the same as the one of
192@func{make-client-socket}.  The optional arguments may specify the
193created socket's behaviour.  If the optional arguments are omitted, then
194the following value should be used as default:
195
196@table @var
197@item ai-family
198Defaults to: @code{*af-inet*}.
199
200@item @var{ai-socktype}
201Defaults to: @code{*sock-stream*}.
202
203@item @var{ai-protocol}
204Defaults to: @code{*ipproto-ip*}.
205@end table
206
207The returned socket may not be closed automatically so it is the users'
208responsibility to close it explicitly.
209
210@quotation
211@strong{For Vicare:} whenever the returned socket object is garbage
212collected, the function @func{socket-close} is automatically applied to
213it.
214@end quotation
215@end defun
216
217
218@defun socket? @var{obj}
219Return @true{} if @var{obj} is a socket object, @false{} otherwise.
220@end defun
221
222@c page
223@node srfi basic-socket spec ops
224@subsubsection Socket operations
225
226
227The following bindings are exported by the libraries @library{srfi :106}
228and @library{srfi :106 socket}.
229
230
231@defun socket-accept @var{socket}
232Wait for an incoming connection request, and return a fresh connected
233client socket.
234@end defun
235
236
237@defun socket-send @var{socket} @var{bv}
238@defunx socket-send @var{socket} @var{bv} @var{flags}
239Send a binary data block to a socket and return the sent data size.
240
241@var{flags} may specify the procedure's behaviour.  If @var{flags} is
242omitted: the default value must be the result of evaluating the form:
243
244@example
245(message-type none)
246@end example
247@end defun
248
249
250@defun socket-recv @var{socket} @var{size}
251@defunx socket-recv @var{socket} @var{size} @var{flags}
252Receive a binary data block from a socket.  If a zero--length bytevector
253is returned: it means the peer connection is closed.
254
255@var{flags} may specify the procedure's behaviour.  If @var{flags} is
256omitted, the default value must be the result of evaluating the form:
257
258@example
259(message-type none)
260@end example
261@end defun
262
263
264@defun socket-shutdown @var{socket} @var{how}
265Shutdown a socket.  @var{how} must be one of the following constants:
266@code{*shut-rd*}, @code{*shut-wr*}, @code{*shut-rdwr*}.
267@end defun
268
269
270@defun socket-close @var{socket}
271Close a socket.  The procedure should not shutdown the given socket: to
272shutdown a socket @func{socket-shutdown} should be called explicitly.
273
274@quotation
275@strong{For Vicare:} it is safe to apply multiple times this function to
276the same @var{socket} object; the first time the socket is closed,
277subsequent times nothing happens.  This function is automatically
278applied to every socket object returned by @func{make-client-socket} and
279@func{make-server-socket} whenever such objects are garbage collected.
280@end quotation
281@end defun
282
283
284@defun socket-descriptor @var{socket}
285This function is a Vicare extension.  Return an exact integer
286representing the underlying socket descriptor; such integer can be used
287as argument to every @posix{} function accepting socket descriptors.
288@end defun
289
290@c page
291@node srfi basic-socket spec port
292@subsubsection Port conversion
293
294
295The following bindings are exported by the libraries @library{srfi :106}
296and @library{srfi :106 socket}.
297
298
299@defun socket-input-port @var{socket}
300@defunx socket-output-port @var{socket}
301Return a fresh binary input or output port associated with a
302@var{socket}, respectively.  Whenever the returned port is closed: the
303associated socket must @strong{not} be closed along.
304
305@quotation
306@strong{For Vicare:} it is fine to use @func{transcoded-port} from
307@rsixlibrary{io ports} to put a textual port on top of the returned
308binary ports.  Example:
309
310@example
311(import (vicare)
312  (prefix (srfi :106) srfi.))
313
314(with-compensations
315  (define socket
316    (compensate
317        (srfi.make-client-socket "reddit.com" "http")
318      (with
319       (srfi.socket-shutdown socket
320         (srfi.shutdown-method read write))
321       (srfi.socket-close socket))))
322
323  (define in-port
324    (compensate
325        (transcoded-port (srfi.socket-input-port socket)
326                         (native-transcoder))
327      (with
328       (close-port in-port))))
329
330  (define ou-port
331    (compensate
332        (transcoded-port (srfi.socket-output-port socket)
333                         (native-transcoder))
334      (with
335       (close-port ou-port))))
336
337  ---)
338@end example
339
340It is also fine to use the returned ports as @var{port} argument to the
341functions @func{select-port}, @func{select-port-readable?},
342@func{select-port-writable?}, @func{select-port-exceptional?}.
343@end quotation
344@end defun
345
346@c page
347@node srfi basic-socket spec control
348@subsubsection Control features
349
350
351The following bindings are exported by the libraries @library{srfi :106}
352and @library{srfi :106 socket}.
353
354
355@defun call-with-socket @var{socket} @var{proc}
356Call a given procedure with a given socket as an argument.  If
357@var{proc} returns: @func{call-with-socket} returns the result of
358@var{proc} and @var{socket} is automatically closed.  If @var{proc} does
359not return: then @var{socket} is not closed automatically.
360@end defun
361
362@c page
363@node srfi basic-socket spec flag
364@subsubsection Flag operations
365
366
367The following bindings must be implemented as macros:
368@code{address-family}, @code{address-info}, @code{socket-domain},
369@code{ip-protocol}, @code{message-type} and @code{shutdown-method}.
370
371The following bindings are exported by the libraries @library{srfi :106}
372and @library{srfi :106 socket}.
373
374
375@deffn Syntax address-family @meta{name}
376Return a proper address family from the given @meta{name}.
377Implementations must support at least following names and must have the
378described behaviour.
379
380@table @code
381@item inet
382Returns @code{*af-inet*}.
383
384@item inet6
385Returns @code{*af-inet6*}.
386
387@item unspec
388Returns @code{*af-unspec*}.
389@end table
390
391Implementations may support more names such as @code{unix} or
392@code{local} or other names.
393@end deffn
394
395
396@deffn Syntax address-info @meta{name} @dots{}
397Return merged address info flags from given @meta{name}.
398Implementations must support at least following names and must have the
399described behaviour.
400
401@table @code
402@item canoname
403@itemx canonname
404Returns @code{*ai-canonname*}.
405
406@item numerichost
407Returns @code{*ai-numerichost*}.
408
409@item v4mapped
410Returns @code{*ai-v4mapped*}.
411
412@item all
413Returns @code{*ai-all*}.
414
415@item addrconfig
416Returns @code{*ai-addrconfig*}.
417@end table
418
419Implementations may support more names.
420@end deffn
421
422
423@deffn Syntax socket-domain @meta{name}
424Return socket domain flags from the given @meta{name}.  Implementations
425must support at least following names and must have the described
426behaviour.
427
428@table @code
429@item stream
430Returns @code{*sock-stream*}.
431
432@item datagram
433Returns @code{*sock-dgram*}.
434@end table
435
436Implementations may support more names.
437@end deffn
438
439
440@deffn Syntax ip-protocol @meta{name}
441Return ip-protocol flag from given @meta{name}.  Implementations must
442support at least following names and must have the described behaviour.
443
444@table @code
445@item ip
446Returns @code{*ipproto-ip*}.
447
448@item tcp
449Returns @code{*ipproto-tcp*}.
450
451@item udp
452Returns @code{*ipproto-udp*}.
453@end table
454
455Implementations may support more names.
456@end deffn
457
458
459@deffn Syntax message-type @meta{name} @dots{}
460Return message type flag from given @var{name}.  The flag can be used
461both by @func{socket-recv} and @func{socket-send}.  Implementations must
462support at least following names and must have the described behaviour.
463
464@table @code
465@item none
466Returns no flag.
467
468@item peek
469Returns @code{*msg-peek*}.
470
471@item oob
472Returns @code{*msg-oob*}.
473
474@item wait-all
475Returns @code{*msg-waitall*}.
476@end table
477
478Implementations may support more names.
479@end deffn
480
481
482@deffn Syntax shutdown-method @meta{name} @dots{}
483Return shutdown method flags from given @meta{names}.  Implementations
484must support at least following names and must have the described
485behaviour.
486
487@table @code
488@item read
489Returns @code{*shut-rd*}.
490
491@item write
492Returns @code{*shut-wr*}.
493@end table
494
495If @func{shutdown-method} is given both @code{read} and @code{write},
496then it must return @code{*shut-rdwr*}.
497@end deffn
498
499
500@deffn Syntax socket-merge-flags @meta{flags} @dots{}
501Merge given @meta{flags} and returns a new flag.
502@end deffn
503
504
505@deffn Syntax socket-purge-flags @meta{base-flag} @meta{flag} @dots{}
506Remove @meta{flag} from @meta{base-flag} if it exists and return a new
507flag.
508@end deffn
509
510@c page
511@node srfi basic-socket spec const
512@subsubsection Constants
513
514
515Implementations must support following constant variables.  All constant
516variable must be consistent with @posix{}'s[1] definition.  The
517following bindings are exported by the libraries @library{srfi :106} and
518@library{srfi :106 socket}.
519
520@c ------------------------------------------------------------
521
522@subsubheading Address family
523
524@table @code
525@item *af-inet*
526Internet domain sockets for use with IPv4 addresses.  This must behave
527the same as @posix{}'s @code{AF_INET}.
528
529@item *af-inet6*
530Internet domain sockets for use with IPv6 addresses.  This must behave
531the same as @posix{}'s @code{AF_INET6}.
532
533@item *af-unspec*
534Unspecified.  This must behave the same as @posix{}'s @code{AF_UNSPEC}.
535@end table
536
537@c ------------------------------------------------------------
538
539@subsubheading Socket domain
540
541@table @code
542@item *sock-stream*
543Byte--stream socket.  This must behave the same as @posix{}'s
544@code{SOCK_STREAM}.
545
546@item *sock-dgram*
547Datagram socket.  This must behave the same as @posix{}'s
548@code{SOCK_DGRAM}.
549@end table
550
551@c ------------------------------------------------------------
552
553@subsubheading Address info
554
555@table @code
556@item *ai-canonname*
557This must behave the same as @posix{}'s @code{AI_CANONNAME}.
558
559@item *ai-numerichost*
560This must behave the same as @posix{}'s @code{AI_NUMERICHOST}.
561
562@item *ai-v4mapped*
563This must behave the same as @posix{}'s @code{AI_V4MAPPED}.
564
565@item *ai-all*
566This must behave the same as @posix{}'s @code{AI_ALL}.
567
568@item *ai-addrconfig*
569This must behave the same as @posix{}'s @code{AI_ADDRCONFIG}.
570@end table
571
572@c ------------------------------------------------------------
573
574@subsubheading IP protocol
575
576@table @code
577@item *ipproto-ip*
578Internet protocol.  This must behave the same as @posix{}'s
579@code{IPPROTO_IP}.
580
581@item *ipproto-tcp*
582Transmission control protocol.  This must behave the same as @posix{}'s
583@code{IPPROTO_TCP}.
584
585@item *ipproto-udp*
586User datagram protocol.  This must behave the same as @posix{}'s
587@code{IPPROTO_UDP}.
588@end table
589
590@c ------------------------------------------------------------
591
592@subsubheading Message type
593
594@table @code
595@item *msg-peek*
596For @code{socket-recv}.  Peeks at an incoming message.  The data is
597treated as unread and the next @code{socket-recv} shall still return
598this data.  This must behave the same as @posix{}'s @code{MSG_PEEK}.
599
600@item *msg-oob*
601For both @code{socket-recv} and @code{socket-send}.  Requests/sends
602out--of--band data.  This must behave the same as @posix{}'s
603@code{MSG_OOB}.
604
605@item *msg-waitall*
606For @code{socket-recv}.  On sockets created with @code{*sock-stream*}
607flag, this requests the procedure block until the full amount of data
608ban be returned.  This must behave the same as @posix{}'s
609@code{MSG_WAITALL}.
610@end table
611
612@c ------------------------------------------------------------
613
614@subsubheading Shutdown method
615
616@table @code
617@item *shut-rd*
618Disables further receive operation.  This must behave the same as
619@posix{}'s @code{SHUT_RD}.
620
621@item *shut-wr*
622Disables further send operations.  This must behave the same as
623@posix{}'s @code{SHUT_WR}.
624
625@item *shut-rdwr*
626Disables further send and receive operations.  This must behave the same
627as @posix{}'s @code{SHUT_RDWR}.
628@end table
629
630@c page
631@node srfi basic-socket examples
632@subsection Examples
633
634
635Simple echo server:
636
637@example
638(import (vicare)
639  (prefix (srfi :106 socket)
640          srfi.))
641
642(define (server-run master-socket)
643  ;;Handle the first pending connection.  If an
644  ;;exception is raised ignore it.
645  (guard (E (else
646             (debug-print (condition-message E))))
647    (srfi.call-with-socket
648        (srfi.socket-accept master-socket)
649      (lambda (server-socket)
650        (with-compensations
651          (define in
652            (compensate
653                (transcoded-port
654                 (srfi.socket-input-port  server-socket)
655                 (native-transcoder))
656              (with
657               (close-port in))))
658          (define ou
659            (compensate
660                (transcoded-port
661                 (srfi.socket-output-port server-socket)
662                 (native-transcoder))
663              (with
664               (close-port ou))))
665          (push-compensation
666           (srfi.socket-shutdown server-socket)
667           (srfi.socket-close    server-socket))
668          (let loop ((line (read-line in)))
669            (unless (eof-object? line)
670              (put-string ou (string-append line "\r\n"))
671              (flush-output-port ou)
672              (loop (read-line in))))))))
673  ;;Handle next pending connection.
674  (server-run master-socket))
675
676(define echo-master-socket
677  (srfi.make-server-socket "8080"))
678
679(server-run echo-master-socket)
680@end example
681
682Simple echo client:
683
684@example
685(import (rnrs)
686  (prefix (srfi :106 socket)
687          srfi.))
688
689(define client-socket
690  (srfi.make-client-socket "localhost" "8080"
691    (srfi.address-family inet)
692    (srfi.socket-domain stream)
693    (srfi.address-info v4mapped addrconfig)
694    (srfi.ip-protocol ip)))
695
696(srfi.socket-send client-socket (string->utf8 "hello\r\n"))
697(display (utf8->string
698          (srfi.socket-recv client-socket
699                            (string-length "hello\r\n"))))
700(flush-output-port (current-output-port))
701(srfi.socket-shutdown client-socket
702                      (srfi.shutdown-method read write))
703(srfi.socket-close client-socket)
704@end example
705
706@c page
707@node srfi basic-socket refs
708@subsection References
709
710
711[1] The Open Group Base Specifications Issue 7:
712
713@center @url{http://pubs.opengroup.org/onlinepubs/9699919799/nframe.html}
714
715@c page
716@node srfi basic-socket copyright
717@subsection Copyright
718
719
720Copyright @copyright{} Takashi Kato (2012) @email{ktakashi@@ymail.com}.@*
721All Rights Reserved.
722
723Permission is hereby granted, free of charge, to any person obtaining a
724copy of this software and associated documentation files (the
725``Software''), to deal in the Software without restriction, including
726without limitation the rights to use, copy, modify, merge, publish,
727distribute, sublicense, and/or sell copies of the Software, and to
728permit persons to whom the Software is furnished to do so, subject to
729the following conditions:
730
731The above copyright notice and this permission notice shall be included
732in all copies or substantial portions of the Software.
733
734THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
735EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
736MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
737IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
738CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
739TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
740SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
741