add and update man pages.

CHANGES

@@ -3,6 +3,8 @@
   Updated to buffer to fix read buffers.  Thanks, David Lichteblau.
   Oops!  byte_copy had a trivial and dumb typo in it that I'm unsure how
     I could have missed it.
+  add mmap man pages.
+  update and add socket man pages.
 
 0.8:
   BSD compatibility.

mmap/mmap_private.3

@@ -0,0 +1,20 @@
+.TH mmap_private 3
+.SH NAME
+mmap_private \- memory map a file for reading and writing
+.SH SYNTAX
+.B #include <mmap.h>
+
+extern char* \fBmmap_private\fP(const char* \fIfilename\fR,unsigned long* \fIfilesize\fR);
+.SH DESCRIPTION
+mmap_private opens \fIfilename\fR for reading and writing, maps the
+whole file into memory, closes the file, writes the length of the file
+to \fIfilesize\fR and returns a pointer to the mapped file.
+
+The file is mapped copy-on-write.  Changes done to the mapped region
+will not be written to disk.
+
+The file is unmapped by the operating system if the process terminates.
+It can also be manually unmapped by calling \fBmunmap\fR from
+<sys/mman.h>.
+.SH "SEE ALSO"
+munmap(2)

mmap/mmap_read.3

@@ -0,0 +1,17 @@
+.TH mmap_read 3
+.SH NAME
+mmap_read \- memory map a file for reading
+.SH SYNTAX
+.B #include <mmap.h>
+
+extern char* \fBmmap_read\fP(const char* \fIfilename\fR,unsigned long* \fIfilesize\fR);
+.SH DESCRIPTION
+mmap_read opens \fIfilename\fR for reading, maps the whole file into
+memory, closes the file, writes the length of the file to \fIfilesize\fR
+and returns a pointer to the mapped file.
+
+The file is unmapped by the operating system if the process terminates.
+It can also be manually unmapped by calling \fBmunmap\fR from
+<sys/mman.h>.
+.SH "SEE ALSO"
+munmap(2)

mmap/mmap_shared.3

@@ -0,0 +1,24 @@
+.TH mmap_shared 3
+.SH NAME
+mmap_shared \- memory map a file for reading and writing
+.SH SYNTAX
+.B #include <mmap.h>
+
+extern char* \fBmmap_shared\fP(const char* \fIfilename\fR,unsigned long* \fIfilesize\fR);
+.SH DESCRIPTION
+mmap_shared opens \fIfilename\fR for reading and writing, maps the
+whole file into memory, closes the file, writes the length of the file
+to \fIfilesize\fR and returns a pointer to the mapped file.
+
+The file is mapped shared.  Changes done to the mapped region are
+written to disk and are visible to other processes reading from the file
+or mapping the same file into memory.
+
+The file is unmapped by the operating system if the process terminates.
+It can also be manually unmapped by calling \fBmunmap\fR from
+<sys/mman.h>.
+
+To write changes to disk immediately, you can use msync from
+<sys/mman.h>.
+.SH "SEE ALSO"
+munmap(2), msync(2)

socket/fmt_ip6_flat.3

@@ -0,0 +1,32 @@
+.TH fmt_ip6_flat 3
+.SH NAME
+fmt_ip6_flat \- write a formatted ASCII representation of an IPv6 number
+.SH SYNTAX
+.B #include <ip6.h>
+
+unsigned int \fBfmt_ip6_flat\fP(char *\fIdest\fR,const char \fIip\fR[16]);
+.SH DESCRIPTION
+fmt_ip6_flat formats an IPv6 number in a flat ASCII representation from
+\fIip\fR and writes the result into \fIdest\fR. It returns the number of
+bytes written (always 32).
+
+This representation does not contain colons and is meant to be easily
+machine-readable.  Use fmt_ip6 for the normal (standard) representation.
+This function is meant for places which use colons to separate fields
+and thus have problems interpreting the standard IPv6 notation.
+
+If \fIdest\fR equals FMT_LEN (i.e. is zero), fmt_ip6_flat returns the
+number of bytes it would have written.
+
+fmt_ip6_flat does not append \\0.
+
+For convenience, ip6.h defines the integer IP6_FMT to be big enough to
+contain every possible fmt_ip6_flat output plus \\0.
+.SH EXAMPLE
+#include <ip6.h>
+
+  char buf[IP6_FMT];
+  char ip[16];
+  buf[fmt_ip6_flat(buf,ip)]=0;
+.SH "SEE ALSO"
+scan_ip6_flat(3), fmt_ip6(3)

socket/scan_ip6.c

@@ -86,28 +86,3 @@ unsigned int scan_ip6(const char *s,char ip[16])
     ip[16-suffixlen+i] = suffix[i];
   return len;
 }
-
-static long int fromhex(unsigned char c) {
-  if (c>='0' && c<='9')
-    return c-'0';
-  else if (c>='A' && c<='F')
-    return c-'A'+10;
-  else if (c>='a' && c<='f')
-    return c-'a'+10;
-  return -1;
-}
-
-unsigned int scan_ip6_flat(const char *s,char ip[16])
-{
-  int i;
-  for (i=0; i<16; i++) {
-    int tmp;
-    tmp=fromhex(*s++);
-    if (tmp<0) return 0;
-    ip[i]=tmp << 4;
-    tmp=fromhex(*s++);
-    if (tmp<0) return 0;
-    ip[i]+=tmp;
-  }
-  return 32;
-}

socket/scan_ip6_flat.3

@@ -0,0 +1,27 @@
+.TH scan_ip6_flat 3
+.SH NAME
+scan_ip6_flat \- parse an IPv6 number in flat ASCII representation
+.SH SYNTAX
+.B #include <ip6.h>
+
+int \fBscan_ip6_flat\fP(const char *\fIsrc\fR,char \fIip\fR[16]);
+.SH DESCRIPTION
+scan_ip6_flat parses an IPv6 number in flat ASCII representation
+from \fIsrc\fR and writes the result into \fIip\fR. It returns the
+number of bytes read from \fIsrc\fR or 0 if the parsing failed.
+
+scan_ip6_flat accepts upper and lower case hex letters.
+
+The flat representation should have been output by fmt_ip6_flat.
+.SH EXAMPLE
+#include <str.h>
+.br
+#include <ip6.h>
+
+  char buf[]="00000000000000000000000000000001";
+  char ip[16];
+  if (scan_ip6_flat(buf,ip) != str_len(buf))
+    parse_error();
+
+.SH "SEE ALSO"
+fmt_ip6_flat(3), scan_ip6(3)

socket/scan_ip6_flat.c

@@ -0,0 +1,26 @@
+#include "haveinline.h"
+
+static inline int fromhex(unsigned char c) {
+  if (c>='0' && c<='9')
+    return c-'0';
+  else if (c>='A' && c<='F')
+    return c-'A'+10;
+  else if (c>='a' && c<='f')
+    return c-'a'+10;
+  return -1;
+}
+
+unsigned int scan_ip6_flat(const char *s,char ip[16])
+{
+  int i;
+  for (i=0; i<16; i++) {
+    int tmp;
+    tmp=fromhex(*s++);
+    if (tmp<0) return 0;
+    ip[i]=tmp << 4;
+    tmp=fromhex(*s++);
+    if (tmp<0) return 0;
+    ip[i]+=tmp;
+  }
+  return 32;
+}

socket/socket_bind4_reuse.3

@@ -0,0 +1,33 @@
+.TH socket_bind4_reuse 3
+.SH NAME
+socket_bind4_reuse \- set the local IP address and port of a socket
+.SH SYNTAX
+.B #include <socket.h>
+
+int \fBsocket_bind4_reuse\fP(int \fIs\fR,char \fIip\fR[4],uint16 \fIport\fR);
+.SH DESCRIPTION
+socket_bind4_reuse sets the local IP address and TCP/UDP port of a
+TCP/UDP socket \fIs\fR to \fIip\fR and \fIport\fR respectively.
+
+If the IP address is 0.0.0.0, the operating system chooses a local IP
+address.  If \fIport\fR is 0, the operating system chooses a port.
+
+Normally socket_bind4_reuse returns 0. If anything goes wrong,
+socket_bind4_reuse returns -1, setting errno appropriately.
+
+Unlike socket_bind4 this function will also tell the operating system
+that the address is to be reused soon, which turns off the normal pause
+before this IP and port can be bound again.
+.SH EXAMPLE
+  #include <socket.h>
+
+  int \fIs\fR;
+  char \fIip\fR[4];
+  uint16 \fIp\fR;
+
+  \fIs\fR = socket_tcp();
+  socket_bind4_reuse(s,ip,p);
+  socket_connect4(s,ip,p);
+
+.SH "SEE ALSO"
+socket_bind6(3)

socket/socket_bind6.3

@@ -4,7 +4,8 @@ socket_bind6 \- set the local IP address and port of a socket
 .SH SYNTAX
 .B #include <socket.h>
 
-int \fBsocket_bind6\fP(int \fIs\fR,char \fIip\fR[16],uint16 \fIport\fR);
+int \fBsocket_bind6\fP(int \fIs\fR, char \fIip\fR[16], uint16 \fIport\fR,
+                 uint32 \fIscope_id\fR);
 .SH DESCRIPTION
 socket_bind6 sets the local IP address and TCP/UDP port of a TCP/UDP
 socket \fIs\fR to \fIip\fR and \fIport\fR respectively.
@@ -15,16 +16,21 @@ address.  If \fIport\fR is 0, the operating system chooses a port.
 Normally socket_bind6 returns 0. If anything goes wrong, socket_bind6
 returns -1, setting errno appropriately.
 
+The \fIscope_id\fR should normally be zero, but for link-local addresses
+it specifies the interface number on which to bind.  The interface
+number for a given network interface name can be found with
+\fBsocket_getifidx\fR.
 .SH EXAMPLE
   #include <socket.h>
 
   int \fIs\fR;
   char \fIip\fR[16];
   uint16 \fIp\fR;
+  uint32 \fIscope_id\fR;
 
   \fIs\fR = socket_tcp6();
-  socket_bind6(s,ip,p);
+  socket_bind6(s,ip,p,scope_id);
   socket_connect6(s,ip,p);
 
 .SH "SEE ALSO"
-socket_bind4(3)
+socket_bind4(3), socket_getifidx(3)

socket/socket_bind6_reuse.3

@@ -0,0 +1,39 @@
+.TH socket_bind6_reuse 3
+.SH NAME
+socket_bind6_reuse \- set the local IP address and port of a socket
+.SH SYNTAX
+.B #include <socket.h>
+
+int \fBsocket_bind6_reuse\fP(int \fIs\fR,char \fIip\fR[16],uint16 \fIport\fR,
+                       uint32 \fIscope_id\fR);
+.SH DESCRIPTION
+socket_bind6_reuse sets the local IP address and TCP/UDP port of a
+TCP/UDP socket \fIs\fR to \fIip\fR and \fIport\fR respectively.
+
+If the IP address is ::, the operating system chooses a local IP
+address.  If \fIport\fR is 0, the operating system chooses a port.
+
+Normally socket_bind6_reuse returns 0. If anything goes wrong,
+socket_bind6_reuse returns -1, setting errno appropriately.
+
+The \fIscope_id\fR should normally be zero, but for link-local addresses
+it specifies the interface number on which to bind.  The interface
+number for a given network interface name can be found with
+\fBsocket_getifidx\fR.
+
+Unlike socket_bind6 this function will also tell the operating system
+that the address is to be reused soon, which turns off the normal pause
+before this IP and port can be bound again.
+.SH EXAMPLE
+  #include <socket.h>
+
+  int \fIs\fR;
+  char \fIip\fR[16];
+  uint16 \fIp\fR;
+
+  \fIs\fR = socket_tcp();
+  socket_bind6_reuse(s,ip,p);
+  socket_connect4(s,ip,p);
+
+.SH "SEE ALSO"
+socket_bind6(3)

socket/socket_connect4.3

@@ -4,7 +4,7 @@ socket_connect4 \- attempt to make a TCP connection
 .SH SYNTAX
 .B #include <socket.h>
 
-int \fBsocket_connect4\fP(int \fIs\fR,char \fIip\fR[4],uint16 \fIport\fR);
+int \fBsocket_connect4\fP(int \fIs\fR,const char \fIip\fR[4],uint16 \fIport\fR);
 .SH DESCRIPTION
 socket_connect4 attempts to make a connection from TCP socket \fIs\fR to
 TCP port \fIport\fR on IP address \fIip\fR.

socket/socket_connect6.3

@@ -4,7 +4,8 @@ socket_connect6 \- attempt to make a TCP connection
 .SH SYNTAX
 .B #include <socket.h>
 
-int \fBsocket_connect6\fP(int \fIs\fR,char \fIip\fR[16],uint16 \fIport\fR,uint32 \fIscope_id\fR);
+int \fBsocket_connect6\fP(int \fIs\fR, const char \fIip\fR[16],
+                    uint16 \fIport\fR,uint32 \fIscope_id\fR);
 .SH DESCRIPTION
 socket_connect6 attempts to make a connection from TCP socket \fIs\fR to
 TCP port \fIport\fR on IP address \fIip\fR.

socket/socket_recv4.3

@@ -0,0 +1,31 @@
+.TH socket_recv4 3
+.SH NAME
+socket_recv4 \- receive a UDP datagram
+.SH SYNTAX
+.B #include <socket.h>
+
+int \fBsocket_recv4\fP(int \fIs\fR, char* \fIbuf\fR, unsigned int \fIlen\fR,
+                 char \fIip\fR[4],uint16* \fIport\fR);
+.SH DESCRIPTION
+socket_recv4 receives up to \fIlen\fR bytes starting at \fIbuf\fR from a UDP
+datagram coming in on the socket \fIs\fR.  It writes the UDP port to
+\fIport\fR and the IP address to \fIip\fR, and returns the number of
+bytes actually received (or -1 if anything went wrong).
+.SH RETURN VALUE
+socket_recv4 returns the number of bytes in the datagram if one was
+received.  If not, it returns -1 and sets errno appropriately.
+.SH EXAMPLE
+  #include <socket.h>
+
+  int \fIs\fR;
+  char \fIip\fR[4];
+  uint16 \fIp\fR;
+  char buf[1000];
+  int len;
+
+  \fIs\fR = socket_tcp();
+  socket_bind4(s,ip,p);
+  len = socket_recv4(s,buf,sizeof(buf),ip,&p);
+
+.SH "SEE ALSO"
+socket_recv6(3)

socket/socket_recv6.3

@@ -0,0 +1,36 @@
+.TH socket_recv6 3
+.SH NAME
+socket_recv6 \- receive a UDP datagram
+.SH SYNTAX
+.B #include <socket.h>
+
+int \fBsocket_recv6\fP(int \fIs\fR, char* \fIbuf\fR, unsigned int \fIlen\fR,
+        char \fIip\fR[16], uint16* \fIport\fR, uint32* \fIscope_id\fR);
+.SH DESCRIPTION
+socket_recv6 receives up to \fIlen\fR bytes starting at \fIbuf\fR from a UDP
+datagram coming in on the socket \fIs\fR.  It writes the UDP port to
+\fIport\fR and the IP address to \fIip\fR, and returns the number of
+bytes actually received (or -1 if anything went wrong).
+
+For link-local addresses, \fIscope_id\fR will become the network
+interface number, which can be translated into the name of the interface
+("eth0") with socket_getifname.
+.SH RETURN VALUE
+socket_recv6 returns the number of bytes in the datagram if one was
+received.  If not, it returns -1 and sets errno appropriately.
+.SH EXAMPLE
+  #include <socket.h>
+
+  int \fIs\fR;
+  char \fIip\fR[16];
+  uint16 \fIp\fR;
+  char buf[1000];
+  int len;
+  uint32 scope_id;
+
+  \fIs\fR = socket_tcp();
+  socket_bind6(s,ip,p);
+  len = socket_recv6(s,buf,sizeof(buf),ip,&p,&scope_id);
+
+.SH "SEE ALSO"
+socket_recv6(3), socket_getifname(3)

socket/socket_send4.3

@@ -0,0 +1,31 @@
+.TH socket_send4 3
+.SH NAME
+socket_send4 \- send a UDP datagram
+.SH SYNTAX
+.B #include <socket.h>
+
+int \fBsocket_send4\fP(int \fIs\fR, const char* \fIbuf\fR, unsigned int \fIlen\fR,
+                 const char \fIip\fR[4],uint16 \fIport\fR);
+.SH DESCRIPTION
+socket_send4 sends \fIlen\fR bytes starting at \fIbuf\fR in a UDP
+datagram over the socket \fIs\fR to UDP port \fIport\fR on IP address
+\fIip\fR.
+
+You can call socket_send4 without calling socket_bind4.  This has the
+effect as first calling socket_bind4 with IP address 0.0.0.0 and port 0.
+.SH RETURN VALUE
+socket_send4 returns 0 if the datagram was sent successfully.  If not,
+it returns -1 and sets errno appropriately.
+.SH EXAMPLE
+  #include <socket.h>
+
+  int \fIs\fR;
+  char \fIip\fR[4];
+  uint16 \fIp\fR;
+
+  \fIs\fR = socket_tcp();
+  socket_bind4(s,ip,p);
+  socket_send4(s,"hello, world",12,ip,p);
+
+.SH "SEE ALSO"
+socket_send6(3)

socket/socket_send6.3

@@ -0,0 +1,37 @@
+.TH socket_send6 3
+.SH NAME
+socket_send6 \- send a UDP datagram
+.SH SYNTAX
+.B #include <socket.h>
+
+int \fBsocket_send6\fP(int \fIs\fR, const char* \fIbuf\fR, unsigned int \fIlen\fR,
+         const char \fIip\fR[16], uint16 \fIport\fR, uint32 \fIscope_id\fR);
+.SH DESCRIPTION
+socket_send6 sends \fIlen\fR bytes starting at \fIbuf\fR in a UDP
+datagram over the socket \fIs\fR to UDP port \fIport\fR on IP address
+\fIip\fR.
+
+You can call socket_send6 without calling socket_bind4.  This has the
+effect as first calling socket_bind4 with IP address :: and port 0.
+
+The meaning of \fIscope_id\fR is dependent on the implementation and
+IPv6 IP.  On link-local IPv6 addresses it specifies the outgoing
+interface index.  The name (e.g. "eth0") for a given interface index can
+be queried with getifname.  \fIscope_id\fR should normally be set to 0.
+.SH RETURN VALUE
+socket_send6 returns 0 if the datagram was sent successfully.  If not,
+it returns -1 and sets errno appropriately.
+.SH EXAMPLE
+  #include <socket.h>
+
+  int \fIs\fR;
+  char \fIip\fR[16];
+  uint16 \fIp\fR;
+  uint32 \fIscope_id\fR;
+
+  \fIs\fR = socket_tcp();
+  socket_bind6(s,ip,p);
+  socket_send6(s,"hello, world",12,ip,p,scope_id);
+
+.SH "SEE ALSO"
+socket_send4(3), socket_getifidx(3)

socket/socket_sendfile.3

@@ -0,0 +1,35 @@
+.TH socket_sendfile 3
+.SH NAME
+socket_sendfile \- send a file over a TCP socket
+.SH SYNTAX
+.B #include <socket.h>
+
+int \fBsocket_sendfile\fP(int \fIout\fR, int \fIin\fR, uint32 \fIoffset\fR,
+                    uint32 \fIbytes\fR);
+.SH DESCRIPTION
+socket_sendfile sends \fIbytes\fR bytes starting at \fIoffset\fR in the
+file \fIin\fR to the socket connected to file descriptor \fIout\fR.
+
+The socket must be connected.
+
+Note that the underlying sendfile system call is system specific and
+currently only implemented on Linux.  On other operating systems, it is
+emulated with a read/write loop.
+.SH RETURN VALUE
+socket_sendfile returns 0 if the data was sent successfully.  If not,
+it returns -1 and sets errno appropriately.
+.SH EXAMPLE
+  #include <socket.h>
+  #include <open.h>
+
+  int \fIs\fR;
+  char \fIip\fR[4];
+  uint16 \fIp\fR;
+  int \fIfd\fR = open_read("/etc/passwd");
+
+  \fIs\fR = socket_tcp();
+  socket_connect4(s,ip,p);
+  socket_sendfile(s,fd,0,23);
+
+.SH "SEE ALSO"
+socket_send6(3)

t.c

@@ -8,15 +8,32 @@
 #include "buffer.h"
 #include "ip4.h"
 #include "mmap.h"
+#include "open.h"
 #include <stdio.h>
+#include <unistd.h>
 
 #define rdtscl(low) \
      __asm__ __volatile__ ("rdtsc" : "=a" (low) : : "edx")
 
 int main(int argc,char* argv[]) {
-  char buf[100];
-  printf("%d\n",fmt_str(buf,"fnord"));
-  printf("%d\n",fmt_str(0,"fnord"));
+  char buf[]="00000000000000000000000000000001";
+  char ip[16];
+  if (scan_ip6_flat(buf,ip) != str_len(buf))
+    buffer_putsflush(buffer_2,"parse error!\n");
+#if 0
+  int fd=open_read("t.c");
+  buffer b;
+  char buf[1024];
+  char line[20];
+  int i;
+  buffer_init(&b,read,fd,buf,1024);
+  i=buffer_getline(&b,line,19);
+  buffer_puts(buffer_1,"getline returned ");
+  buffer_putulong(buffer_1,i);
+  buffer_puts(buffer_1,"\n");
+  buffer_puts(buffer_1,line);
+  buffer_flush(buffer_1);
+#endif
 #if 0
   buffer_putulong(buffer_1,23);
 //  buffer_putspace(buffer_1);