[Spread-cvs] cvs commit: spread/daemon/docs libsp.3 SP_receive.3

[jonathan at spread.org]

jonathan    02/04/02 02:09:39

  Modified:    daemon/docs SP_receive.3
  Added:       daemon/docs libsp.3
  Log:
  Added new manpage for libsp.3 also updated SP_receive manpage with better
  information on handling X_TOO_SHORT errors.
  
  Revision  Changes    Path
  1.2       +30 -5     spread/daemon/docs/SP_receive.3
  
  Index: SP_receive.3
  ===================================================================
  RCS file: /storage/cvsroot/spread/daemon/docs/SP_receive.3,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- SP_receive.3	21 Aug 2001 14:28:21 -0000	1.1
  +++ SP_receive.3	2 Apr 2002 07:09:38 -0000	1.2
  @@ -1,9 +1,9 @@
   .\" Process this file with
   .\" groff -man -Tascii foo.1
   .\"
  -.TH SP_RECEIVE 3 "JULY 1998" SPREAD "User Manuals"
  +.TH SP_RECEIVE 3 "April 2002" Spread "User Manuals"
   .SH NAME
  -SP_receive, SP_scat_receive \- Receive message from spread
  +SP_receive, SP_scat_receive \- Receive message from Spread
   .SH SYNOPSIS
   .B #include <sp.h>
   .sp
  @@ -84,13 +84,28 @@
   
   .I Endian_mismatch
   will be set to true (1) if the endianness of the sending machine 
  -differs from that of this receiving machine.
  +differs from that of this receiving machine. If the 
  +.B BUFFER_TOO_SHORT 
  +error is returned then the endian_mismatch field will be set to the size of 
  +the incoming message as a negative value. So if the message requires 300 bytes
  +of buffer space and only 200 bytes was provided in the 
  +.I mess 
  +buffer, 
  +.I endian_mismatch 
  +will be set to \-300.
   
   The actual message body being received will be passed into the buffer given by
   .I mess
   which is at least 
   .I max_mess_len 
  -bytes in size. If the message being received is larger then this buffer the  extra
  +bytes in size. If the message being received is larger then this buffer the default
  +behaivor will be to return a 
  +.B BUFFER_TOO_SHORT 
  +error and provide the required length in the 
  +.I endian_mismatch 
  +field. If the DROP_RECV flag was passed in the 
  +.I service_type
  +field, then as much data as possible will be returned and the extra
   data will be discarded by the system and the return value of 
   .B SP_receive
   will indictate an error.
  @@ -296,10 +311,20 @@
   During communication to receive the message communication errors occured
   and the receive could not be completed.
   .TP
  +.B GROUPS_TOO_SHORT
  +If the 
  +.I groups
  +array is too short to hold the entire list of groups this message was sent to 
  +then this error is returned and the 
  +.I num_groups 
  +field will be set to the negative of the number of groups needed.
  +.TP
   .B BUFFER_TOO_SHORT
   If the message body buffer
   .I mess
  -is too short to hold the message being received, this is returned.
  +is too short to hold the message being received then this error is returned and the 
  +.I endian_mismatch 
  +field is set to the negative value of the required buffer length.
   .SH BUGS
   None.
   .SH AUTHOR
  
  
  
  1.1                  spread/daemon/docs/libsp.3
  
  Index: libsp.3
  ===================================================================
  .\" Process this file with
  .\" groff -man -Tascii foo.1
  .\"
  .TH SP 3 "April 2002" Spread "User Manuals"
  .SH "NAME"
  libsp \- Spread Group Communication Client Library
  .SH "SYNOPSIS"
  .SH "DESCRIPTION"
  The Spread 
  .B libsp
  library implements the client SP interface to the Spread
  group communication or multicast message bus system.
  .SH "DATA STRUCTURES"
  .SH "HEADER FILES"
  .I sp.h
  is the main header and includes necessary defines and types. It also 
  includes the other header files sp_events.h and sp_func.h.
  
  .I sp_events.h
  declares the types and functions that make up the E Event-management 
  library.
  
  .I sp_func.h
  declares the functions of the SP interface. Since sp.h includes this you
  should not include this directly.
  .SH "FILES"
  No files are required for client applications using the SP library.
  .SH "DIAGNOSTICS"
  The library will not output any debugging information except in fatal errors.
  The 
  .B SP_error(3)
  function can be used to print an informative error message when SP functions
  return an error code.
  .SH "BUGS"
  None currently known. Library is only thread-safe if the program
  is linked with libtsp.a not libsp.a.  The non-thread-safe library is
  provided for those who are writing single-threaded applications and do not
  want to pay the minimal performance penalty for locking.
  .SH AUTHOR
  Yair Amir <yairamir at cnds.jhu.edu>
  .PP
  Jonathan Stanton <jonathan at cnds.jhu.edu>
  .PP
  Spread Project <spread at spread.org>
  .SH "SEE ALSO"
  .BR spread (1)
  .BR SP_connect (3)
  .BR SP_disconnect (3)
  .BR SP_equal_group_ids (3)
  .BR SP_error (3)
  .BR SP_join (3)
  .BR SP_leave (3)
  .BR SP_multicast (3)
  .BR SP_scat_multicast (3)
  .BR SP_multigroup_multicast (3)
  .BR SP_multigroup_scat_multicast (3)
  .BR SP_poll (3)
  .BR SP_receive (3)
  .BR SP_scat_receive (3)