BCI NET/BCI NET Dec 94.iso/archives/networking/misc/socket_lib10a.lha/socket.doc

Text File | 1994-02-23 | 19.0 KB | 495 lines

               S O C K E T . L I B R A R Y - E M U L A T I O N
               ===============================================

[  No, it's not one of these fancy AmigaGuide® documents.  Consider me one of
these  old  fashioned  Unix  hackers,  which prefer writing code over writing
documentation ]


COPYRIGHT

This program is © 1993, 1994 by Henning Schmiedehausen.  All rights reserved.

This  program is Chocolade-Ware.  If you find it useful, feel free to send me
a bar of chocolade or two (I like 'Milka Vollmilch').

I  will  not  distribute  the  source  of  this software at the current time,
because  it  is  programmed  after  a  documentation  file,  which  is (C) by
Commodore 1990, 1991, 1992 and still under non-disclosure.

I  can  tell  you  something  about the compatibility, but if you need *real*
documentation,  it  is  necessary,  that  you  become  an  official Commodore
Developer  and  sign  a  non-disclosure  agreement  with Commodore to receive
autodocs on the AS225R2 package.

The  whole  program  and  all  files  in  this  archive  are (C) 1994 Henning
Schmiedehausen.  All rights reserved.  This is freely distributable software,
not Public Domain.


AUTHOR

Henning Schmiedehausen
Marquardsenstraße 3
D-91054 Erlangen
Germany

EMail:
[e-mail]

The program was written with CygnusED 3.5 and compiled with SAS C V 6.3 using
the  3.1  AUK,  the  AmiTCP  includes  and the AS225R2 developer kit.
(I'm an official Commodore developer, so this is legal)

It  was  tested and debugged on two A3000 with AmigaOS 3.1 using a Picasso II
Gfx Board, some Ariadne Ethernet Boards and AmiTCP 2.3.


DISTRIBUTION

This  program  may be copied and freely distributed via electronic media such
as  Mailboxes,  Internet  and  Usenet,  as long as the integrity of the whole
archive is kept and this README is included without any changes.

You  are  allowed  to re-pack this archive with other compressing methods, as
long as all files are kept unmodified in such a new archive.

You  are  not  allowed to add any files to the archive, delete any files from
the archive or modify any of the files in the archive.

Especially  BBS  sysops  are  not  allowed  to  add any advertisments to this
archive or to any of the files of the archive.

If you find any archive with such BBS ads, please send them to me.

This  software  may  only  be included in freely distributable Disk and CDROM
libraries  with  the  written  permission  of  the author.  If you want to be
added, please send me a stamped, self addressed envelope.

This permission is herewith given for

The Fred Fish Library (including the CD ROM releases)
The Fred Fish Library on CD ROM
SAAR AG PD Series
The AmiNet CD ROM's from Walnut Creek


DISCLAIMER

The following disclaimer is for the program called 'socket.library', from now
on called 'program'.

I  hereby  reject  any  liability  or  responsibility  for these or any other
consequences from the use of 'program' whatsoever.  This includes, but is not
limited  to,  damage to your equipment, to your data, personal injuries, loss
of money, loss of hair, loss of concience or any other kinds of side effects.

Although  'program'  has been tested thoroughly on some different machines, I
cannot rule out the possibility that 'program'

   * is somehow incompatible to your equipment

   * has bugs that show up on your equipment

   * does not do what it is supposed to do on your equipment

It  is  your  responsiblity  to  take  any  precautions  necessary to protect
yourself  from these or any other effects.  I explicitly reject any liability
or responsibility from the consequences of you using 'program'.

And  for  our  german  friends,  who feel the urge to express certain politic
statements with the distribution of their software:

Hiermit  sei  es ausdrücklich gestattet diese Software zu all jenen Dingen zu
gebrauchen,  die kleinkarierte Dogmatiker ihren potentiellen Kunden verbieten
wollen,   also   beispielsweise   die   Übertragung   der  Wasserstoffbomben-
konstruktionsunterlagen an Killer-Mutanten vom Mars oder der Verkauf an Arme,
die   der   kostenfreien  Beschaffungsmöglichkeiten  von  frei  vertreibbarer
Software unkundig sind.  Dennoch wird um Zusendung von Schokolade gebeten.


THANKS

* The AmiTCP group, consisting of
        Tomi Ollila    <[e-mail]>
        Pekka Pessi    <[e-mail]>
        Markus Peuhkuri    <[e-mail]>
        Jarno Rajahalme    <[e-mail]>

  for bringing such a superb program like AmiTCP to the Amiga community.

  ... and for rolling the ball to me.

*  All the folks at the Commodore developer support for providing us with at
   least a little information

*  Ken Dyke and Randell Jesup for answering lots of silly questions

*  David Swasbrook, Author of 'SwazInfo', where I stole the upper part of the
   Disclaimer

*  Lutz Vieweg; I stole the german 'Disclaimer' from his TWC archive :-)
   (You'll get a chocolade next time you come to an Amiga meeting.  :-)

*  My Beta-Testers:
      The AmiTCP group  -    [e-mail]
      Markus Illenseer  -    [e-mail]
      Hakan Tandogan    -    [e-mail]
      Rudolf Neuhaus    -    [e-mail]
      Thomas Kroener    -    [e-mail]
      Carsten Heyl      -    [e-mail]
      Matthias Scheler  -    [e-mail]
      Timo Rossi        -    [e-mail]
      Cor Bosman        -    [e-mail]
      Chris Mattingly   -    [e-mail]
      Michael B. Smith  -    [e-mail]
      Michael C. Taylor -    [e-mail]
      Ty Sarna          -    [e-mail]
      Dale Luck         -    [e-mail]
      Mike Meyer        -    [e-mail]

*  The nice people who live in the appartment on the floor above and tolerate
   programming sessions till 5am without knocking on my door

*  :-) Guess, who. :-)

*  All the folks from #amigager, who much too often successfully distracted me
   from my real work.


NEEDED EQUIPMENT

- Amiga computer, running AmigaOS 2.04 or beyond.
  2.1 or better is recommended (see get_tz)

- AmiTCP installed; V 2.3 or beyond is recommended

- Some basic grip to TCP/IP software


WHAT IS IT FOR

Currently,  networking  on the Amiga is in a terrible situation:

There is an official TCP/IP package from Commodore, called AS225R2, but it is
not  released yet and only available to official Commodore Devlopers.  Due to
the situation of Commodore, I do not expect them to release it any time soon.
This  package  has  the  advantage of containing well ported clients and some
servers, including an NFS Server for the Amiga.  Unfortunately, almost nobody
has it.

Then there is AmiTCP.  Brand new, a little rugged, but a great effort, Freely
distributable and comes with full source.  Every programmers dream.

You can guess, what happened:  Both protocol stacks come with different APIs.
Programs, which run under AmiTCP will not work under AS225 and vice versa.

Most  of the people who develop TCP/IP software for the Amiga, write (in this
desparate situation) their software for both both protocol stacks and put for
every program two archives on the ftp sites.

I  always  thought,  that  this  is  the  wrong  approach  to the problem.  I
investigated  both possibilities to unify the APIs of AmiTCP and AS225, but I
always thought that the AmiTCP API is in many way superior to AS225 API.

Due to some problems (I will tell you later), only one approach is possible:

Putting  an AS225R2 compatible socket.library on top of AmiTCP.

This  library enables, most of the AS225 client programs to run under AmiTCP,
and make the transition from AS225 to AmiTCP as smooth as possible.

I tried the following client programs for AS225:

Original-Commodore:

finger         - works
ftp            - works with KLUDGE switch (see below)
nfsmgr         - works
showmount      - works
ping           - works
rsh            - works
rlogin         - works

nfsd           - works

rcp            - this program is linked with the socket-link library. It will
                 never run. No chance to emulate.

Shell-Telnet   from Matthias Scheler: works
AmigaIrc Alpha from Petra Zeidler:    works


INSTALLATION

Make a directory called 'AmiTCP:LIBS'
Copy the socket.library file to this directory.


VERSION

Don't  be  confused  by the version of the socket.library.  Many of the older
AS225 programs rely on a socket.library V 4.x.  So the library adds itself as
'socket.library  V  4.4' to the system.  You can find out the real version of
the socket.library mit 'version file libs:socket.library'.


USAGE

AmiTCP *must* be started, before any program can open socket.library.

Most  of  the AS225 programs open 'Inet:libs/socket.library'.  To work around
this,  you must load the library into memory before using it (or the programs
will  say 'cannot open socket.library').  There is a 'loadlib' tool provided,
which can do this for you.
You  use it as 'loadlib AmiTCP:libs/socket.library' Best thing will be to put
it into your AmiTCP:bin/startnet file.

You  can  also  make an assign 'ASSIGN INET:  AmiTCP:'.  This will solve your
problem without any library-loading.  You have one more assign, though.


CONFIG FILES

The library needs two things:

-  The  hostname  of your Amiga must be set in ENV:HOSTNAME *WITHOUT* domain.
   e.g. setenv HOSTNAME forge (this is my hostname)

-  You  need  a  environment  variable  called  'ENV:SOCKETCONFIG'  with  the
   following options:

   UID/N/A    - User ID of the user at the console

   GID/N/A    - Group ID of the user at the console

   USER/A     - Name of the user at the console

   DOMAIN/A   - Domain of your Amiga *without* leading dot

   UMASK/A/N  - Umask for NFS writes

   KLUDGE/S   - see below

   An example is:

   setenv SOCKETCONFIG "UID=200 GID=200 USER=barnard DOMAIN=franken.de UMASK=002"


Well, then you should be ready to go.


COMPATIBILITY (that's what you've waited for)

Well,  at  first I thought of this whole project as impossible.  That's why I
put  it back again and again (I first had the thought right after the release
of AmiTCP 1.0)

But   then   again   I   looked   at   it   and   some   UseNet  Articles  in
comp.sys.amiga.datacomm  seemed to imply that it *can* be done.  AS225 is, as
far  as  I  know,  derived from the BSD 4.3 Networking code, while the AmiTCP
comes  from the Mach BSD port of the Berkley Net/2 release.  So, they are not
too different from each other.  After looking at the fuction calls, it seemed
to possible.


COMPATIBILITY ISSUES

- library calls

  - The following calls have been ported and should work without any drawbacks:

    setup_sockets, cleanup_sockets, socket, s_close, s_getsignal,
    gethostbyname, gethostbyaddr, inet_addr, inet_makeaddr, inet_lnaof,
    inet_netof, inet_network, inet_ntoa, listen, recv, send, shutdown,
    setsockopt, getsockopt, getnetbyaddr, getnetbyname, getprotobyname,
    getprotobynumber, getservbyname, getservbyport, getpwuid, getpwnam,
    getpeername, getsockname, gethostname, s_syslog, rcmd

  - strerror
      AmiTCP  does  not  contain a system call for returning an error string.
      (Shame  on  you  folks.   This increases every AmiTCP user program by 2
      KBytes  for  useless  strings)  I  took  the  strings  from  the  AS225
      sys/errno.h file.

  - getuid, getgid, getlogin, getdomainname, getumask, umask
      AmiTCP has (to my knowledge) no concept of the user at the console. It
      seems to be always the root user. These calls return the contents of
      the ENV:SOCKETCONFIG file:

      getuid:        UID
      getgid:        GID
      getlogin:      USER
      getdomainname: DOMAIN
      getumask:      UMASK

  - getgroups
      Gets only the primary group of the user.

  - get_tz
      AmiTCP has some nice code featuring locale.library to get the offset.
      I use it also for get_tz. AS225 just reads it from its config file.

  - select, selectwait
      NUMFD is bigger for AS225 than for AmiTCP.  AS225 uses fd_sets with 128
      Bits,  for FD masks while AmiTCP uses fd_sets, which have only 64 Bits.
      This seems not much of a problem for me, because most programs won't us
      that  much sockets, but you have been noticed.  If you think, that this
      is a problem, recompile AmiTCP with 128 Bits for FD_SETSIZE.

      NOTE:   I  was  pretty impressed that AS225 identically to AmiTCP has a
      call   like  'selectwait  /  WaitSelect',  which  is  not  only  almost
      identically named but has almost the same parameters.  The AmiTCP folks
      say,  that  they haven't seen the AS225 API before releasing AmiTCP, so
      it seems to be a logic extension to the BSD stuff. I haven't tested it
      under all circumstances, but it seems to work

  - accept, bind, connect, recvfrom, sendto
      AmiTCP  has  a  different  idea  than AS225 of what a 'struct sockaddr'
      should  be.  (This not the fault of the AmiTCP folks, but of the people
      who  moved 4.3 into the Net/2 Release.  :-) ) I wrote a wrapper for all
      These  functions,  it should work, but I do not claim responsibility if
      this is one reason for failure.

  - s_ioctl
      The first tough one. AmiTCP has total different codes for its ioctls.
      I've supported only the following IOCTL's:

       SIOCATMARK, FIONBIO, FIONREAD, FIOASYNC, SIOCSPGRP, SIOCGPGRP

      Of course this effectivly keeps almost everything not related to
      sockets from running. But then again, these are only:

        SIOCADDRT, SIOCDELRT - for route support, so the AS225
        'route' command and the 'routed' will not work

        [NOTE: Somebody told me, that the routed *does* run, but is not
        able to add new routes, which it gets from other routed's via RIP
        into the AmiTCP route tables. But it should be able to broadcast
        its known routes to other machines on the net. I didn't test it
        but IMHO it is possible. I have neither connection to a bigger
        public network nor the possibility to test this in deep. ]

        SIOCSIFADDR, SIOCGIFADDR, SIOCSIFDSTADDR, SIOCGIFDSTADDR,
        SIOCSIFFLAGS, SIOCGIFFLAGS, SIOCGIFBRDADDR, SIOCSIFBRDADDR,
        SIOCGIFNETMASK, SIOCSIFNETMASK, SIOCGIFMETRIC, SIOCSIFMETRIC,
        SIOCGIFCONF

        this keeps also the 'ifconfig' and 'netstat' commands from working

        SIOCSARP, SIOCGARP, SIOCDARP

        this kills the 'arp' command.

        NOTE:   Even  if  you  implement the ioctl's you won't be able to run
        ifconfig from AS225, because AmiTCP uses different (IMHO silly) names
        for  the  interfaces.  Why didn't they omit the '.device'?  'ifconfig
        slip/0'  would  be  sooo  nice.   :-)  (Consider  this an enhancement
        request)

        NOTE2:   Most  of  the ioctls are also there in AmiTCP.  However, the
        structures  used in AmiTCP and AS225 are *very* different (there seem
        to  be heavy changes in the 4.3->Net/2 transition).  I consider these
        ioctls less important, so I dropped this from this release.

        SIOCSSLIPDEV, SIOCSIFMTU, SIOCGIFMTU

        These ioctls() are missing completly, they're not in AmiTCP.

  - getpwent, endpwent, setpwent
      They're in there. However, I do not recommend to use them.

  - s_dev_list
      This  is  a  funny  one.  AS225 uses this one to map the list of socket
      descriptors to the list of file descriptors of SAS C 5.  This call does
      no  longer  work  with  SAS C 6, because there this list is no longer a
      static  array but a linked list.  I could have skipped this call if not
      for the 'ftp' program:

      If  s_dev_list()  does  nothing, the AS225 'ftp' client no longer works
      correct.  You won't see any output from it.  It seems to me, that some-
      how, 'ftp' uses this file<->socket relation; maybe the programmer wrote
      a wrapper to use sockets as files.  I don't know.

      This is, where the 'KLUDGE' switch from the config file comes in:
      If you enter 'KLUDGE' in the config-file, socket.library will claim the
      first  eight  sockets  of  every open library base and return no socket
      numbers below '8'.  Then 'ftp' works.  Don't ask me, why, though.  :-)

      I don't really like this kludge; I don't think, any of the user supplied
      programs for AS225 will ever make real use of this call, especially not
      under  SAS  C  6.x.   So  you  may  need this kludge only for the 'ftp'
      client.  If you will not use it, don't set it.

  -  setnetent,  endnetent, getnetent, setprotoent, endprotoent, getprotoent,
     setservent, endservent, getservent, sethostent, endhostent, gethostent

      These are internal calls to access various files (networks, protocols,
      services, hosts).  Will not be supported.  Don't use them.

  -  reconfig
      Not supported. Should be possible via sending an ARexx Command to the
      stack.  I can't think of an application to use this.

  -  s_release, s_inherit
      These are the bad guys.  Not supported, I doubt that they ever will be.
      (I  have no idea, how) This prevents *every* AS225 server from running,
      because  AmiTCP  uses  a  different (BETTER!) protocol to give a socket
      from inetd to a started server.

  -  recvmsg, sendmsg
      Advanced send() and recv(). Should be implementable without too much
      hassle, but I didn't need it.... :-)

- structures

  Well, most of the structures needed are identical (Thank god) or don't care
  (sockets).   I had to deal explicitly with two:  passwd and sockaddr.
  Both wrappers should work fine.

CONCLUSION

Well,  so  much for that.  This library now pretty much fills *my* needs.  If
you  have any ideas or if you find bugs, tell me.  My EMail address is listed
above.   I  will  not  implement  anything  new until I need it or get public
demand.   If find programs that run (...that not run) which are not mentioned
in the list above, please send me a mail.

BTW: The writing of a bsdsocket.library to sit on AS225:

Sorry, but thats IMHO not possible. Several reasons:

a)  The  brain  damaged way, AmiTCP handles its Password file.  The calls for
    that  (along  with  the  group  stuff  and  gethostname)  are in a *LINK*
    library.   Pretty  much  all  user programs, who need this stuff carry it
    around in its binary.  So you can't write a library to redirect.  I hope,
    this will be changed in AmiTCP 3.0 or beyond.  (But I think, it's already
    too late.  :( )

b)  The missing strerror() call. Same as above

c)  Totally different signal structure. AS225 allocates its signals and gives
    the user the ability to query them via getsignal().
    AmiTCP just offers a call to set complete masks for the signals. To come
    from AmiTCP to AS225 is easy (allocate two signals in the library base,
    give them to AmiTCP and return them on getsignal()). But how to emulate
    the setting of masks?

ENHANCEMENT REQUEST (Not really...  :-) )

I  desperatly  need  an  SMTP  and an NNTP client and a SMTPd and a NNTPd for
AmiTCP.   Is  there nobody out there, who will write this stuff?  I'm willing
to Beta-test...


HISTORY

 7. 1. 94  - V 1.0ß - First Beta release (including a release for the KA '94
                                          German Amiga Users Meeting)

20. 2. 94  - V 1.0  - First public release


-- © Henning Schmiedehausen 1994 - All rights reserved