TABLE OF CONTENTS socket.library/accept socket.library/Background socket.library/bind socket.library/ByteOrder socket.library/cleanup_sockets socket.library/ConfigureInet socket.library/connect socket.library/endgrent socket.library/endhostent socket.library/endnetent socket.library/endprotoent socket.library/endpwent socket.library/endservent socket.library/FD_SET socket.library/getdomainname socket.library/getgid socket.library/getgrent socket.library/getgrgid socket.library/getgrnam socket.library/getgroups socket.library/gethostbyaddr socket.library/gethostbyname socket.library/gethostent socket.library/gethostname socket.library/getlogin socket.library/getnetbyaddr socket.library/getnetbyname socket.library/getnetent socket.library/getpeername socket.library/getprotobyname socket.library/getprotobynumber socket.library/getprotoent socket.library/getpwent socket.library/getpwnam socket.library/getpwuid socket.library/getservbyname socket.library/getservbyport socket.library/getservent socket.library/getsockname socket.library/getsockopt socket.library/getuid socket.library/getumask socket.library/get_tz socket.library/inet_addr socket.library/inet_aton socket.library/inet_lnaof socket.library/inet_makeaddr socket.library/inet_netof socket.library/inet_network socket.library/inet_ntoa socket.library/listen socket.library/rcmd socket.library/reconfig socket.library/recv socket.library/select socket.library/selectwait socket.library/send socket.library/setgid socket.library/setgrent socket.library/sethostent socket.library/setnetent socket.library/setprotoent socket.library/setpwent socket.library/setservent socket.library/setsockopt socket.library/setuid socket.library/setup_sockets socket.library/shutdown socket.library/socket socket.library/strerror socket.library/syslog socket.library/s_close socket.library/s_crypt socket.library/s_dev_func socket.library/s_dev_list socket.library/s_dup socket.library/s_dup2 socket.library/s_errno socket.library/s_getsignal socket.library/s_inherit socket.library/s_ioctl socket.library/s_release socket.library/s_syslog socket.library/umask socket.library/accept socket.library/accept NAME accept -- Accept new connection from socket. SYNOPSIS ns = accept (s, name, len) D0 D0 A0 A1 int accept (int, struct sockaddr *, int *); FUNCTION Servers using TCP (or another connection-oriented protocol) accept() connections initiated by a client program. The connections are generally accept()ed on a socket which on which bind() and listen() have been executed. Unless there is an error, accept() will return a new socket which is connected to the client. The server can then use the new socket ('ns') to communicate with the client (via send() and recv()) and still accept() new connections on the old socket ('s'). 'Len' should be initialized to the amount of space pointed to by 'name.' The actual size of 'name' will be returned in 'namelen' and 'name' will contain the name of the socket initiating the connect(). This saves the server from needing to do a getpeername() for new connections. accept() generally blocks until a client attempts a connect(). You may use select() to determine whether a connection is pending, or use a non-blocking socket (see setsockopts()). INPUTS s - socket descriptor. name - name of the peer socket. len - pointer to the length of the sockaddr struct. The value returned will be the actual size of the sockaddr struct that was returned. RESULT ns - new socket descriptor or -1 (errno will be set to reflect exact error condition). EXAMPLE NOTES BUGS SEE ALSO socket(), bind(), listen() socket.library/Background socket.library/Background What is a socket library? The standard programmer's interface to network protocols on most Un*x machines is the Berkley socket abstraction. It is usually provided as a link library. You should have as documentation the books "Unix Network Programming" by W. Richard Stephens (Prentice-Hall, 1990) and "Internetworking with TCP/IP, Volume II" by Douglas Comer and David Stephens (Prentice-Hall, 1991). We don't get a kick-back from Prentice-Hall, but we do use these books every day and we do know that writing programs using TCP/IP and sockets can be difficult. Why a shared socket library? A shared library provides many benefits. First, it greatly reduces code size. Second, it is compiler-independent. However, the most important benefit is that it is easily upgradable. New libraries with bug fixes, speed improvements, or additional functions can be utilized by existing code without recompilation. In the case of the socket library, this means we can later add support for name resolution, better configuration, DES, etc. Who should use this? Everyone. Our primary goal in writing this socket library is compatibility. BSD, SVR4, X/Open, POSIX and OSF sources have been consulted when necessary. All standard Unix socket functions, with all their peculiarities have been faithfully ported :^) Unfortunately, due to the fact that these functions were not designed with shared libraries or the Amiga in mind, some compromises were made. How to use this? See "What is a socket library?" above. To port existing socket code (from Un*x), you must: OpenLibrary the socket.library and call setup_sockets() not call read() or write() on sockets (use send() and recv()) call s_close() rather than close() for sockets call s_ioctl() rather than ioctl() for sockets On Un*x machines, the calls read(), write(), close(), ioctl(), etc. functions are just calls to the kernel which can deal with sockets and other files. Obviously, this is not possible with a shared library on a machine where these functions come from link libraries, hence the s_*() functions. About errno: 'C' programmers should be familiar with the global variable 'errno.' It is used extensively in standard socket implementations to provide details about error conditions. We take care of this in the shared library by passing a pointer to 'errno' into the shared library with setup_sockets(). You can, of course, pass a pointer to any longword-aligned, four-byte chunk of memory you own, so this will work for non-'C'-language programmers. About integers: All integers are assumed to be 32-bit. None are specified as long in order to maintain Un*x compatibility. If you are using a compiler which doesn't use 32-bit ints, you must make sure that all ints are converted to longs by your code. About assembly langauge: To be complete, we probably should include assembly header files. We don't. About the get*() functions: This is standard with the Un*x functions, too, but is worth noting: These function return a pointer to a static buffer. The buffer returned by a call to getX*() is cleared on the next invocation of getX*(). For example, the buffer pointed to by the return of gethostent() is cleared by a call to gethostent(), gethostbyaddr() or gethostbyname(), but not by a call to getprotoent(), etc. As noted in the autodocs, none of the get*ent(), set*ent() or end*ent() functions should normally be used except in porting existing programs (and internally). About library bases: The shared socket library returns a different library base for each OpenLib() and uses these different library bases to keep track of some global data for each opener. If you start a new process with a new context, the new process must open and initialize socket.library. Mere tasks should not access the socket.library, only processes should. Example: /* your includes */ #include #include #include #include #include #include #include #include #include /* the next two lines must always be here */ #include /* this is the maximum number of sockets that you want */ #define MAXSOCKS 10 main() { if((SockBase = OpenLibrary( "inet:libs/socket.library", 6L )) == NULL) { printf("Error opening socket.library\n"); exit(10); } setup_sockets( MAXSOCKS, &errno ); /* normal socket code... (see AS225 dev disk for complete examples) */ cleanup_sockets(); CloseLibrary( SockBase ) ; } Legalese: This shared socket library (and it's documentation) are Copyright © 1995 Interworks. All Rights Reserved. The shared socket library was based on code from Commodore, Inc., written by Martin Hunt. This version was written by Jim Cooper and Michael B. Smith of Interworks. Documentation by Jim Cooper, Michael B. Smith, and others. Parts of this shared socket library and the associated header files are derived from code which is: Copyright (c) 1980-1995 Regents of the University of California. All rights reserved. Redistribution and use in source and binary forms are permitted provided that the above copyright notice and this paragraph are duplicated in all such forms and that any documentation, advertising materials, and other materials related to such distribution and use acknowledge that the software was developed by the University of California, Berkeley. The name of the University may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. socket.library/bind socket.library/bind NAME bind -- Bind a name to a socket. SYNOPSIS return = bind (s, name, namelen) D0 D0 A1 D1 int bind (int, struct sockaddr *, int); FUNCTION Assigns a name to an unnamed socket. Connection-oriented servers generally bind() a socket to a well- known address and listen() at that socket, accept()ing connections from clients who know the address. Connectionless servers generally bind() a socket to a well-known address and recvfrom() that socket. Most servers should build 'name' from a well-known port obtained from getservbyname(). Hard-coded ports are often used in prototype servers, but should never be used in production code. For more information on port numbering, see your favorite TCP/IP refrence. INPUTS s - socket descriptor. name - address to bind to socket 's.' namelen - length (in bytes) of 'name.' RESULT return - 0 if successful else -1 (errno will contain the specific error). EXAMPLE NOTES BUGS SEE ALSO socket(), listen(), accept() socket.library/ByteOrder socket.library/ByteOrder NAME byteorder -- Macros to convert between host and network byte order. SYNOPSIS #include #include netlong = htonl ( hostlong ); netshort = htons ( hostshort); hostlong = ntohl ( netlong ); hostshort = ntohs ( netshort); FUNCTION These routines convert between host byte order to network byte order. This is necessary because not all CPUs store words and longs in the same manner. Some CPUs, called "Big Endian," store words as high byte followed by low byte. Others, called "Little Endian," store a word as low byte followed by high byte. Big endian machines include IBM mainframes and Motorola 68000 family machines. Little endian machines include DEC VAXen and Intel 80x86 family CPUs. Network order is big endian. Therefore, on big endian machines, these functions are null macros. EXAMPLE NOTES These macros are provided for portability. They are null macros on the Amiga. #define htons(x) (x) #define ntohs(x) (x) #define htonl(x) (x) #define ntohl(x) (x) SEE ALSO socket.library/cleanup_sockets socket.library/cleanup_sockets NAME cleanup_sockets -- Free global data for sockets. SYNOPSIS cleanup_sockets (); void cleanup_sockets (void); FUNCTION This function frees all signals and allocated memory. It closes all open sockets. This function should be called after all socket functions are completed and before CloseLibrary(). INPUTS None. RESULT None. NOTES Since 'socks' is now allocated in the library initialization code, we do the deallocation in the library cleanup. Also, since we aren't allocating based on the 'maxsocks' parameter to setup_sockets(), we scan the entire array - we don't just stop at the 'maxsocks - 1' entry, in case they overran their original request. This takes care of the program requesting 0 sockets, but opening one anyway... BUGS SEE ALSO setup_sockets() socket.library/ConfigureInet socket.library/ConfigureInet NAME ConfigureInetA -- Set or change socket.library configuration states SYNOPSIS ConfigureInetA (taglist) A0 void ConfigureInetA (struct TagItem *); FUNCTION Allows the caller to manipulate certain socket.library operating parameters, such as whether I-Net 225 operates as a gateway or not. INPUTS taglist - A taglist containing tags defined in RESULT None. EXAMPLE NOTES I-Net 225 ONLY. BUGS SEE ALSO socket.library/connect socket.library/connect NAME connect -- Connect to socket. SYNOPSIS return = connect (s, name, namelen) D0 D0 A1 D1 int connect (int, struct sockaddr *, int); FUNCTION To communicate with a server using a connection-oriented protocol (i.e. TCP), the client must connect() a socket obtained by the client (from socket()) to the server's well-known address. (The server will receive (from accept()) a new socket which is connected to the socket which the client is connect()ing to the server.) Clients of a connectionless server (i.e. one using UDP) can use connect() and send() rather than always using sendto(). In this case, no actual connection is created, the address to send to is just stored with the socket. Most clients should build 'name' from a well-known port obtained from getservbyname(). Hard-coded ports are often used in prototype clients, but should never be used in production code. For more information on port numbering, see your favorite TCP/IP refrence. INPUTS s - socket descriptor. name - address of socket to connect 's' to. namelen - length of 'name.' RESULT return - 0 if successful else -1 (errno will contain the specific error). EXAMPLE NOTES BUGS SEE ALSO socket(), bind(), listen(), accept() socket.library/endgrent socket.library/endgrent NAME endgrent - Closes the group file. SYNOPSIS endgrent () void endgrent (void); FUNCTION Closes the group file if it was open. Resets the 'flag' that may have been set by setgrent(). INPUTS None. RESULT None. NOTES I-Net 225 ONLY. SEE ALSO getgrent(), setgrent() socket.library/endhostent socket.library/endhostent NAME endhostent -- Closes the hosts file ("INet:db/hosts"). SYNOPSIS endhostent () void endhostent (void); FUNCTION Closes the host file if it is open. Only needed if sethostent() or gethostent() have been called. INPUTS None. RESULT None. EXAMPLE NOTES BUGS SEE ALSO gethostent(), gethostbyname(), gethostbyaddr(), sethostent() socket.library/endnetent socket.library/endnetent NAME endnetent -- Closes the networks file. SYNOPSIS endnetent () void endnetent (void); FUNCTION Closes the host file if it is open. This is only needed if setnetent() or getnetent() has been called. INPUTS None. RESULT None. EXAMPLE NOTES BUGS SEE ALSO getnetent(), getnetbyname(), getnetbyaddr(), setnetent() socket.library/endprotoent socket.library/endprotoent NAME endprotoent -- Closes the protocols file. SYNOPSIS endprotoent () void endprotoent (void); FUNCTION Closes the protocols file if it is open. This function is needed only if getprotoent() or setprotoent() have been called. INPUTS None. RESULT None. EXAMPLE NOTES BUGS SEE ALSO getprotoent(), setprotoent(), getprotobyname(), getprotobynumber() socket.library/endpwent socket.library/endpwent NAME endpwent - Closes the password file. SYNOPSIS endpwent () void endpwent (void); FUNCTION Closes the password file if it was open. Reset the 'flag' which may have been set by setpwent(). INPUTS None. RESULT None. SEE ALSO getpwent(), setpwent() socket.library/endservent socket.library/endservent NAME endservent -- Closes the services file. SYNOPSIS endservent () void endservent (void); FUNCTION Closes the services file if it is open. This function is needed only if setservent() or getservent() have been called. INPUTS None. RESULT None. EXAMPLE NOTES BUGS SEE ALSO setservent(), getservent() socket.library/FD_SET socket.library/FD_SET NAME FD_SET -- Macros to manipulate socket masks. SYNOPSIS #include FD_SET(socket, mask) FD_CLR(socket, mask) result = FD_ISSET(socket, mask) FD_ZERO(mask) FUNCTION Type fd_set contains masks for use with sockets and select() just like longs can contain masks for use with signals and Wait(). Unlike signal masks, you can't manipulate socket masks with boolean operators, instead you must use the FD_*() macros. FD_SET() sets the "bit" for 'socket' in 'mask.' FD_CLR() clears the "bit" for 'socket' in 'mask.' FD_ISSET() returns non-zero if the "bit" for 'socket' in 'mask' is set, else zero. FD_ZERO() clears all "bits" in 'mask.' FD_ZERO should be used to initialize an fd_set variable before it is used. EXAMPLE SEE ALSO select(), selectwait() socket.library/getdomainname socket.library/getdomainname NAME getdomainname -- Get domain name. SYNOPSIS return = getdomainname (name, namelen) D0 A1 D1 int getdomainname (char *, int); FUNCTION Returns the name of the domain into the pointer specified. Name will be null-terminated if sufficient space is available. To find out what a domain name is, check your favorite TCP/IP reference. INPUTS name - pointer to character buffer. namelen - space available in 'name.' RESULT 0 is returned if successful. -1 is returned on error. EXAMPLE NOTES There is currently no corresponding setdomainname() function. Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". BUGS SEE ALSO socket.library/getgid socket.library/getgid NAME getgid -- Get group id. SYNOPSIS #include gid = getgid () D0 gid_t getgid (void); FUNCTION returns the user's group id INPUTS None. RESULT gid - group ID or -1 (on error). EXAMPLE NOTES This is an emulation of the Unix getgid() function. The Unix getegid() is equivalent to getgid() on the Amiga. Note that the user has one primary group ID, but may have several additional secondary group IDs which can only be obtained with getgroups(). Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". BUGS SEE ALSO getgroups(), getuid() socket.library/getgrent socket.library/getgrent NAME getgrent -- Read the next line in the group file. SYNOPSIS group = getgrent () D0 struct group *getgrent (void); FUNCTION There is usually no reason to call this function directly. It is called internally by getgrgid() and getgrnam(). It is provided only for Un*x compatibility. Opens the group file if necessary. Returns the next entry in the file in a group structure. INPUTS None. RESULT group - a pointer to a filled in group structure if successful, else NULL. struct group { char *gr_name; char *gr_passwd; char *gr_gecos; gid_t gr_gid; char **gr_mem; }; NOTES I-Net 225 ONLY. SEE ALSO getgrgid(), getgrnam(), setgrent(), endgrent() socket.library/getgrgid socket.library/getgrgid NAME getgrgid -- Search group database for a particular gid. SYNOPSIS #include passwd = getgrgid (gid) D0 D1 struct group *getgrgid (gid_t); FUNCTION getgrgid() returns a pointer to a group structure. The group structure fields are filled in from the fields contained in one line of the group file. INPUTS gid - gid of group entry to look up. RESULT group - a pointer to a group struct with its elements filled in from the group file. struct group { char *gr_name; char *gr_passwd; char *gr_gecos; gid_t gr_gid; char **gr_mem; }; NOTES The group structure is returned in a buffer that will be overwritten on the next call to getgr*(). I-Net 225 ONLY. SEE ALSO getgrnam() socket.library/getgrnam socket.library/getgrnam NAME getgrnam -- Search group database for a particular name. SYNOPSIS #include group = getgrnam (name) D0 A0 struct group *getgrnam (char *); FUNCTION getgrnam() returns a pointer to a group structure. The group structure fields are filled in from the fields contained in one line of the group file. INPUTS name - group name of group entry to look up. RESULT group - a pointer to a group struct with its elements filled in from the group file. struct group { char *gr_name; char *gr_passwd; char *gr_gecos; gid_t gr_gid; char **gr_mem; }; NOTES The group structure is returned in a buffer that will be overwritten on the next call to getgr*(). I-Net 225 ONLY. SEE ALSO getgrgid() socket.library/getgroups socket.library/getgroups NAME getgroups -- Get group access list. SYNOPSIS #include #include num = getgroups (max_gids, gids) D0 D0 A0 int getgroups (int, gid_t *); FUNCTION The array "gids" is filled with the group ids that the current user belongs to (including the primary gid). The list may be up to "max_gids" long. The actual number of gids is returned in 'num.' INPUTS max_gids - length of gids array. gids - gid_t array. RESULT num - the number of gids is returned if successful. No errors are currently defined. EXAMPLE gid_t gids [8]; int number_of_gids; number_of_gids = getgroups (8, gids); NOTES Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". The upper limit of groups that can be returned by getgroups() is NGROUP (in ). BUGS This routine has had problems including the primary gid. These problems should be fixed, so please report if you see this bug. SEE ALSO getgid(), getuid() socket.library/gethostbyaddr socket.library/gethostbyaddr NAME gethostbyaddr -- Get host entry from the hosts file. SYNOPSIS #include #include host = gethostbyaddr (addr, len, type ) D0 A0 D0 D1 struct hostent *gethostbyaddr (char *, int, int); FUNCTION Opens the host file if necessary. Finds the entry for 'addr' and returns it in a hostent structure. If "usedns=true" is set in INet:s/inet.config, and INet:db/resolv.conf is set up, then a DNS request will be made for the information, if it is not present in the hosts file. struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* host address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ #define h_addr h_addr_list[0] /* messed up for historical reasons */ }; INPUTS addr - internet address, in network byte order. (This is really a long.) len - sizeof(addr), usually 4 type - usually AF_INET RESULT host - pointer to struct hostent for host 'addr.' NULL on EOF or failure to open hosts file. EXAMPLE NOTES The only type currently in use is AF_INET. The buffer pointed to by 'host' will be overwritten by the next call to gethost*(). BUGS SEE ALSO gethostbyname() socket.library/gethostbyname socket.library/gethostbyname NAME gethostbyname -- Get host entry from the hosts file. SYNOPSIS #include #include host = gethostbyname (name) D0 A0 struct hostent *gethostbyname (char *); FUNCTION Opens the host file if necessary. Finds the entry for "name" and returns it in a hostent structure. If "usedns=true" is set in INet:s/inet.config, and INet:db/resolv.conf is set up, then a DNS request will be made for the information, if it is not present in the hosts file. struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* host address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ #define h_addr h_addr_list[0] /* messed up for historical reasons */ }; INPUTS RESULT host - pointer to struct hostent for host 'name.' NULL on EOF or failure to open hosts file. EXAMPLE NOTES The buffer pointed to by 'host' will be overwritten by the next call to gethost*(). BUGS SEE ALSO gethostbyaddr() socket.library/gethostent socket.library/gethostent NAME gethostent -- Get host entry from the hosts file ("INet:db/hosts"). SYNOPSIS #include #include #include host = gethostent () D0 struct hostent *gethostent (void); FUNCTION There is normally no reason to use this function. It is used internally by gethostbyname() and gethostbyaddr(). It is provided only for Unix compatibility and even Unix is phasing it out in favor of other methods of name resolution. Opens the host file if necessary. Returns the next entry in the file in a hostent structure. struct hostent { char *h_name; /* official name of host */ char **h_aliases; /* alias list */ int h_addrtype; /* host address type */ int h_length; /* length of address */ char **h_addr_list; /* list of addresses from name server */ #define h_addr h_addr_list[0] /* messed up for historical reasons */ }; INPUTS None. RESULT host - pointer to struct hostent NULL on EOF or failure to open host file. EXAMPLE NOTES The buffer pointed to by 'host' will be overwritten by the next call to gethost*(). BUGS SEE ALSO sethostent(), gethostbyname(), gethostbyaddr(), endhostent() socket.library/gethostname socket.library/gethostname NAME gethostname -- Get the name of your Amiga. SYNOPSIS return = gethostname (name, length) D0 A0 D0 int gethostname (char *, int); FUNCTION Copies the null-terminated hostname to 'name'. The hostname will be truncated if insufficient space is available in 'name'. INPUTS name - pointer to a character array. length - size of the character array. RESULT return - 0 if successful, else -1. NOTES Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". BUGS SEE ALSO socket.library/getlogin socket.library/getlogin NAME getlogin -- Get login name. SYNOPSIS name = getlogin () D0 char *getlogin (void); FUNCTION Returns a pointer to the current user name. INPUTS None. RESULT name - a pointer to the current user name or NULL to indicate an error. You can use this pointer for as long as necessary, but do not write to it. NOTES Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". There is no support for multiple user IDs on a single Amiga because the Amiga OS has no concept of multiple users. socket.library/getnetbyaddr socket.library/getnetbyaddr NAME getnetbyaddr -- Get net entry from the networks file. SYNOPSIS #include net = getnetbyaddr (net, type ) D0 D0 D1 struct netent *getnetbyaddr (long, int); FUNCTION Opens the networks file if necessary. Returns the entry with a matching address in a nettent structure. struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ int n_addrtype; /* net address type */ unsigned long n_net; /* network # */ }; INPUTS net - network number. type - network number type, currently AF_INET. RESULT net - netent structure if succesful, NULL on EOF on failure to open networks file. EXAMPLE NOTES The netent structure is returned in a buffer that will be overwritten on the next call to getnet*(). BUGS SEE ALSO getnetbyname() socket.library/getnetbyname socket.library/getnetbyname NAME getnetbyname -- Get net entry from the networks file. SYNOPSIS #include net = getnetbyname (name) D0 A0 struct netent *getnetbyname (char *); FUNCTION Opens the networks file if necessary. Returns the entry with a matching name in a nettent structure. struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ int n_addrtype; /* net address type */ unsigned long n_net; /* network # */ }; INPUTS name - network name. RESULT net - netent structure if succesful, NULL on EOF on failure to open networks file. EXAMPLE NOTES The netent structure is returned in a buffer that will be overwritten on the next call to getnet*(). BUGS SEE ALSO getnetbyaddr() socket.library/getnetent socket.library/getnetent NAME getnetent -- Get net entry from the networks file. SYNOPSIS #include net = getnetent () D0 struct netent *getnetent (void); FUNCTION This function should not normally be used. It is called internally by getnetbyname() and getnetbyaddr(). Opens the networks file if necessary. Returns the next entry in the file in a nettent structure. struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ int n_addrtype; /* net address type */ unsigned long n_net; /* network # */ }; INPUTS None. RESULT net - netent structure if succesful, NULL on EOF on failure to open networks file. EXAMPLE NOTES The netent structure is returned in a buffer that will be overwritten on the next call to getnet*(). BUGS SEE ALSO setnetent(), getnetbyname(), getnetbyaddr(), endnetent() socket.library/getpeername socket.library/getpeername NAME getpeername -- Get name of connected peer. SYNOPSIS return = getpeername (s, name, namelen) D0 D0 A0 A1 int getpeername (int, struct sockaddr *, int *); FUNCTION For every connected socket, there is a socket at the other end of the connection. To determine the address of the socket at the other end of a connection, pass getpeername() the socket on your end. 'Namelen' should be initialized to the amount of space pointed to by 'name.' The actual size of 'name' will be returned in 'namelen.' INPUTS s - socket descriptor. name - pointer to a struct sockaddr. namelen - initialized to size of 'name.' On return this contains the actual sizeof(name) RESULT return - 0 if successful else -1 (errno will contain the specific error). EXAMPLE NOTES BUGS SEE ALSO bind(), accept(), getsockname() socket.library/getprotobyname socket.library/getprotobyname NAME getprotobyname -- find a protocol entry by name SYNOPSIS #include proto = getprotobyname (name) D0 A0 struct protoent *getprotobyname (char *); FUNCTION Opens the protocols file if necessary. Returns the entry with a matching name in a protoent structure. struct protoent { char *p_name; /* official protocol name */ char **p_aliases; /* alias list */ int p_proto; /* protocol # */ }; INPUTS name - name of prototype to return. RESULT proto - pointer to struct protoent for protocol 'name.' NULL on EOF or failure to open protocols file. EXAMPLE NOTES The protoent structure is returned in a buffer that will be overwritten on the next call to getproto*() BUGS SEE ALSO getprotobynumber() socket.library/getprotobynumber socket.library/getprotobynumber NAME getprotobynumber -- find a protocol entry by number SYNOPSIS #include proto = getprotobynumber (proto) D0 D0 struct protoent *getprotobynumber (int); FUNCTION Opens the protocols file if necessary. Returns the entry with a matching protocol number in a protoent structure. struct protoent { char *p_name; /* official protocol name */ char **p_aliases; /* alias list */ int p_proto; /* protocol # */ }; INPUTS proto - number of prototype to return. RESULT proto - pointer to struct protoent for protocol 'number.' NULL on EOF or failure to open protocols file. EXAMPLE NOTES The protoent structure is returned in a buffer that will be overwritten on the next call to getproto*() BUGS SEE ALSO getprotobyname() socket.library/getprotoent socket.library/getprotoent NAME getprotoent -- Get a protocol entry from the protocols file. SYNOPSIS #include proto = getprotoent () struct protoent *getprotoent (void); FUNCTION There is normally no reason to use this function. It is used internally by getprotobyname() and getprotobynumber(). It is provided only for Unix compatibility. Opens the protocols file if necessary. Returns the next entry in the file in a protoent structure. struct protoent { char *p_name; /* official protocol name */ char **p_aliases; /* alias list */ int p_proto; /* protocol # */ }; INPUTS None. RESULT proto - NULL on EOF or failure to open protocols file. EXAMPLE NOTES The protoent structure is returned in a buffer that will be overwritten on the next call to getproto*() BUGS SEE ALSO getprotobyname(), getprotobynumber(), setprotoent(), endprotoent() socket.library/getpwent socket.library/getpwent NAME getpwent -- Read the next line in the password file. SYNOPSIS passwd = getpwent () D0 struct passwd *getpwent (void); FUNCTION There is usually no reason to call this function directly. It is called internally by getpwuid() and getpwnam(). It is provided only for Un*x compatibility. Opens the password file if necessary. Returns the next entry in the file in a passwd structure, or NULL if at EOF. struct passwd { char *pw_name; char *pw_dir; char *pw_passwd; char *pw_gecos; uid_t pw_uid; gid_t pw_gid; char *pw_shell; /* currently unused */ char *pw_comment; }; INPUTS None. RESULT passwd - a pointer to a filled in passwd structure if successful, else NULL. SEE ALSO getpwuid(), getpwnam(), setpwent(), endpwent() socket.library/getpwnam socket.library/getpwnam NAME getpwnam -- Search user database for a particular name. SYNOPSIS #include passwd = getpwnam (name) D0 A0 struct passwd *getpwnam (char *); FUNCTION getpwnam() returns a pointer to a passwd structure. The passwd structure fields are filled in from the fields contained in one line of the password file. INPUTS name - user name of passwd entry to look up. RESULT passwd - a pointer to a passwd struct with its elements filled in from the passwd file, or NULL if it cannot be found for this name. struct passwd { char *pw_name; char *pw_dir; char *pw_passwd; char *pw_gecos; uid_t pw_uid; gid_t pw_gid; char *pw_shell; /* currently unused */ char *pw_comment; }; NOTES The passwd structure is returned in a buffer that will be overwritten on the next call to getpw*(). SEE ALSO getpwuid() socket.library/getpwuid socket.library/getpwuid NAME getpwuid -- Search user database for a particular uid. SYNOPSIS #include passwd = getpwuid (uid) D0 D1 struct passwd *getpwuid (uid_t); FUNCTION getpwuid() returns a pointer to a passwd structure. The passwd structure fields are filled in from the fields contained in one line of the password file. INPUTS uid - uid of passwd entry to look up. RESULT passwd - a pointer to a passwd struct with its elements filled in from the passwd file, or NULL if it cannot be found for this uid. struct passwd { char *pw_name; char *pw_dir; char *pw_passwd; char *pw_gecos; uid_t pw_uid; gid_t pw_gid; char *pw_shell; /* currently unused */ char *pw_comment; }; NOTES The passwd structure is returned in a buffer that will be overwritten on the next call to getpw*(). SEE ALSO getpwnam() socket.library/getservbyname socket.library/getservbyname NAME getservbyname -- Find a service entry by name. SYNOPSIS #include serv = getservbyname (name, proto) D0 A0 A1 struct servent *getservbyname (char *, char *); FUNCTION Opens the services file and finds the service with the matching name and protocol. struct servent { char *s_name; /* official service name */ char **s_aliases; /* alias list */ int s_port; /* port # */ char *s_proto; /* protocol to use */ }; INPUTS name - name of service to look up. proto - protocol of service to look up. RESULT serv - pointer to struct servent for service 'name.' NULL on EOF or failure to open protocols file. EXAMPLE NOTES The servent structure is returned in a buffer that will be overwritten on the next call to getserv*(). BUGS SEE ALSO getservent(), getservbyport() socket.library/getservbyport socket.library/getservbyport NAME getservbyport -- Find a service entry by port. SYNOPSIS #include serv = getservbyport (port, proto) D0 D0 A0 struct servent *getservbyport (u_short, char *); FUNCTION Opens the services file and finds the service with the matching port and protocol. struct servent { char *s_name; /* official service name */ char **s_aliases; /* alias list */ int s_port; /* port # */ char *s_proto; /* protocol to use */ }; INPUTS RESULT serv - pointer to struct servent for service 'name.' NULL on EOF or failure to open protocols file. EXAMPLE NOTES The servent structure is returned in a buffer that will be overwritten on the next call to getserv*(). BUGS SEE ALSO getservent(), getservbyname() socket.library/getservent socket.library/getservent NAME getservent -- Get a service entry from the services file. SYNOPSIS #include serv = getservent (void) D0 struct servent *getservent (void); FUNCTION There is normally no reason to use this function. It is used internally by getservbyname() and getservbyport(). It is provided only for Unix compatibility. Opens the services file if necessary. Returns the next entry in the file in a servent structure. struct servent { char *s_name; /* official service name */ char **s_aliases; /* alias list */ int s_port; /* port # */ char *s_proto; /* protocol to use */ }; INPUTS None. RESULT serv - pointer to struct servent for next service. NULL on EOF or failure to open protocols file. EXAMPLE NOTES The servent structure is returned in a buffer that will be overwritten on the next call to getserv*() BUGS SEE ALSO setservent(), getservbyname(), getservbyport(), endservent() socket.library/getsockname socket.library/getsockname NAME getsockname -- Get the name of a socket. SYNOPSIS return = getsockname (s, name, namelen) D0 D0 A0 A1 int getsockname (int, struct sockaddr *, int *); FUNCTION Returns the name (address) of the specified socket. 'Namelen' should be initialized to the amount of space pointed to by 'name.' The actual size of 'name' will be returned in 'namelen.' INPUTS s - socket descriptor. name - socket name. namelen - size of 'name' (in bytes). RESULT return - 0 if successful else -1 (errno will be set to one of the following error codes: EBADF invalid socket EXAMPLE NOTES BUGS SEE ALSO bind(), getpeername() socket.library/getsockopt socket.library/getsockopt NAME getsockopt -- Get socket options. SYNOPSIS return = getsockopt (s, level, optname, optval, optlenp) D0 D0 D1 D2 A0 A1 int getsockopt (int, int, int, char *, int *); FUNCTION Gets the option specified by 'optname' for socket 's.' This is an advanced function. See the "sys/socket.h" header and your favorite TCP/IP reference for more information on options. INPUTS s - socket descriptor. level - protocol level. Valid levels are: IPPROTO_IP IP options IPPROTO_TCP TCP options SOL_SOCKET socket options optname - option name. optval - pointer to the buffer which will contain the answer. optlen - initially sizeof(optval). reset to new value on return RESULT return - 0 if successful else -1 (errno will contain the specific error). EXAMPLE NOTES BUGS SEE ALSO setsockopt() socket.library/getuid socket.library/getuid NAME getuid -- Get user id. SYNOPSIS #include uid = getuid () D0 uid_t getuid (void); FUNCTION Returns the user id. INPUTS None. RESULT uid - user ID or -1 (on error). EXAMPLE NOTES This is an emulation of the Unix getuid() function. The Unix geteuid() is equivalent to getuid() on the Amiga. Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". There is no support for multiple user IDs on a single Amiga because the Amiga OS has no concept of multiple users. BUGS SEE ALSO getgid(), getgroups() socket.library/getumask socket.library/getumask NAME getumask -- Get user file creation mask. SYNOPSIS #include umask = getumask () D0 mode_t getumask (void); FUNCTION Returns the umask. RESULT -1 will be returned and an error message will be displayed if there is a problem reading the current configuration. EXAMPLE NOTES THIS IS AN AMIGA-SPECIFIC FUNCTION. It is not a standard Unix function. See umask(). Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". BUGS SEE ALSO umask() socket.library/get_tz socket.library/get_tz NAME get_tz -- Get timezone offset. SYNOPSIS offset = get_tz () D0 short get_tz (void); FUNCTION Returns the number offset from UTC (Universal Time Coordinated, formerly Greenwich Mean Time) in minutes west of UTC. RESULT offset - offset in minutes or -1. NOTES THIS IS AN AMIGA-ONLY FUNCTION. Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". BUGS Does not account for daylight savings time. If the time is really important to you (or hosts you communicate with) you must currently change your INet:s/inet.config for daylight savings/standard time. socket.library/inet_addr socket.library/inet_addr NAME inet_addr -- make internet address from string SYNOPSIS #include #include #include addr = inet_addr (string) D0 A1 u_long inet_addr (char *); FUNCTION Converts a string to an internet address. All internet addresses are in network order. INPUTS string address string. "123.45.67.89" for example RESULT A long representing the network address in network byte order. INADDR_NONE is returned if input is invalid. EXAMPLE NOTES BUGS SEE ALSO socket.library/inet_aton socket.library/inet_aton NAME inet_aton -- make internet address from string SYNOPSIS #include #include #include rslt = inet_aton (string, addr) D0 A0 A1 int inet_aton (char *, struct in_addr *); FUNCTION Check whether "string" is a valid ASCII representation of an Internet address, and if so, convert to a binary address and store that in "addr". INPUTS string address string. "123.45.67.89" for example RESULT 1 if the address if valid, 0 if not. EXAMPLE NOTES This should replace inet_addr(), the return value of which cannot distinguish between failure and a local broadcast address. I-Net 225 ONLY. Not available in Surfer. BUGS SEE ALSO socket.library/inet_lnaof socket.library/inet_lnaof NAME inet_lnaof -- give the local network address SYNOPSIS #include #include #include addr = inet_lnaof( in ) D0 D1 int inet_lnaof ( struct in_addr ); FUNCTION Returns the local network address. INPUTS in - struct in_addr to find local network part of. struct in_addr { u_long s_addr; /* a long containing the internet address */ }; RESULT addr - the local network address portion of 'in.' EXAMPLE NOTES 'in' is *NOT* a pointer to a struct in_addr, it IS a structure. It is a 4-byte structure and is a passed as a structure (rather than a long or pointer to a structure) for historical reasons. RESULT EXAMPLE NOTES BUGS SEE ALSO inet_addr(), inet_makeaddr(), inet_netof() socket.library/inet_makeaddr socket.library/inet_makeaddr NAME inet_makeaddr -- make internet address from network and host SYNOPSIS #include #include #include addr = inet_makeaddr (net, lna) D0 D0 D1 struct in_addr inet_makeaddr (int, int); FUNCTION Formulate an Internet address from network + host. Used in building addresses stored in the ifnet structure. 'in' is *NOT* a pointer to a struct in_addr, it IS a structure. It is a 4-byte structure and is a passed as a structure (rather than a long or pointer to a structure) for historical reasons. See NOTES. INPUTS net - network number in local integer format. lna - local node address in local integer format. RESULT in - struct in_addr. struct in_addr { u_long s_addr; /* a long containing the internet address */ }; EXAMPLE NOTES 'in' is *NOT* a pointer to a struct in_addr, it IS a structure. It is a 4-byte structure and is a passed as a structure (rather than a long or pointer to a structure) for historical reasons. BUGS SEE ALSO inet_addr(), inet_lnaof(), inet_netof() socket.library/inet_netof socket.library/inet_netof NAME inet_netof -- give the network number of an address SYNOPSIS #include #include #include net = inet_netof( in ) D0 D1 int inet_netof( struct in_addr ); FUNCTION Returns the network number. INPUTS in - struct in_addr to find network part of. struct in_addr { u_long s_addr; /* a long containing the internet address */ }; RESULT net - network part of 'in.' EXAMPLE NOTES 'in' is *NOT* a pointer to a struct in_addr, it IS a structure. It is a 4-byte structure and is a passed as a structure (rather than a long or pointer to a structure) for historical reasons. BUGS SEE ALSO inet_addr(), inet_makeaddr(), inet_lnaof() socket.library/inet_network socket.library/inet_network NAME inet_network -- make network number from string SYNOPSIS #include #include #include net = inet_network( string ) D0 A1 int inet_network( char * ); FUNCTION Converts a string to an network number if the string contains the dotted-decimal representation of a network number. All network numbers are in network order. INPUTS string - network string. "123.45.67.89" for example. RESULT net - INADDR_NONE is returned if input is invalid, else the network number corresponding to 'string.' EXAMPLE NOTES BUGS SEE ALSO socket.library/inet_ntoa socket.library/inet_ntoa NAME inet_ntoa -- turn internet address into string SYNOPSIS #include #include #include string = inet_ntoa( in ) D0 D1 char *inet_ntoa ( struct in_addr ); FUNCTION Converts an internet address to an ASCII string in the format "a.b.c.d" (dotted-decimal notation). INPUTS in - struct in_addr. struct in_addr { u_long s_addr; /* a long containing the internet address */ }; RESULT Pointer to a string containing the ASCII ethernet address. For example, if in.s_addr = 0xc009d203 then a pointer to the string "192.9.210.3" is returned. NOTES The result points to a static buffer that is overwritten with each call. 'in' is *NOT* a pointer to a struct in_addr, it IS a structure. It is a 4-byte structure and is a passed as a structure (rather than a long or pointer to a structure) for historical reasons. BUGS SEE ALSO socket.library/listen socket.library/listen NAME listen -- Indicate willingness to accept() connections. SYNOPSIS return = listen (s, backlog) D0 D0 D1 int listen (int, int); FUNCTION This function is used for a connection-oriented server (i.e. one using the TCP protocol) to indicate that it is waiting to receive connections. It is usually executed after socket() and bind(), and before accept(). INPUTS s - socket descriptor. backlog - max number of connection requests to queue (usually 5). RESULT return - 0 is returned if successful, else -1. On error, errno will be set to one of the following: EBADF - s is not a valid descriptor ENOTSOCK - s is not a socket ECONNREFUSED - connection refused, normally because the queue is full EOPNOTSUPP - s is a socket type which does not support this operation. s must be type SOCK_STREAM. BUGS 'backlog' is currently limited to 5, although this is completely arbitrary. SEE ALSO accept(), bind(), connect(), socket() socket.library/rcmd socket.library/rcmd NAME rcmd - Allow superuser to execute commands on remote machines SYNOPSIS rem = rcmd( ahost, inport, luser, ruser, cmd, fd2p ) D0 D0 D1 A0 A1 A2 D2 int rcmd( char **, u_short, char *, char *, char *, int *); FUNCTION This function is used by rsh and rcp to communicate with rshd. The rcmd subroutine looks up the host *ahost using gethostbyname, returning (-1) if the host does not exist. Otherwise *ahost is set to the standard name of the host and a connection is established to a server residing at the well-known Internet port inport. If the call succeeds, a socket of type SOCK_STREAM is returned to the caller and given to the remote command as stdin and stdout. If fd2p is nonzero, then an auxiliary channel to a control process will be set up, and a descriptor for it will be placed in *fd2p. The control process will return diagnostic output from the command (unit 2) on this channel, and will also accept bytes on this channel as being UNIX signal numbers, to be forwarded to the process group of the command. If fd2p is 0, then the stderr (unit 2 of the remote command) will be made the same as the stdout and no provision is made for sending arbitrary signals to the remote process, although you may be able to get its attention by using out-of-band data. INPUTS ahost - pointer to a pointer to a host name. inport - an Internet port. luser - the local user's name. ruser - the remote user's name. cmd - the command string to be executed. fd2p - a flag telling whether to use an auxillary channel. RESULT rem - socket of type SOCK_STREAM if successful, else -1. socket.library/reconfig socket.library/reconfig NAME reconfig - re-initialize the internal configuration structure SYNOPSIS return = reconfig () D0 BOOL reconfig (void); FUNCTION Causes the socket library to read the INet:s/inet.config file. This is useful for when you have changed an entry in the file and need the system to recognize the change without a system reboot. INPUTS None RESULT Boolean return - TRUE upon success, FALSE upon error NOTES Make -no- assumptions about how this works internally. It is generally safe to change any of the values in inet.config, but be aware that while some will take immediate effect (e.g., usedns), others may not have any effect until after a network restart (e.g., changing syslogconsole after the SYSLOG window is already visible). Also, programs that have stored values based on the contents of inet.config will likely not re-read that information until they are restarted. BUGS SEE ALSO socket.library/recv socket.library/recv NAME recv, recvfrom, recvmsg -- Receive a message from a socket. SYNOPSIS #include #include numbytes = recv (s, buf, len, flags) D0 D0 A0 D1 D2 numbytes = recvfrom (s, buf, len, flags, from, fromlen) D0 D0 A0 D1 D2 A1 A2 numbytes = recvmsg (s, msg, flags) D0 D0 A0 D1 int recv (int, char *, int, int) int recvfrom (int, char *, int, int, struct sockaddr *, int *) int recvmsg (int, struct msghdr *, int) FUNCTION recv() is used to receive messages on an already connect()'ed socket. recvfrom() receives data from a socket whether it is in a connected state or not. recvmsg() is the most general of the recv calls and is for advanced use. If no data is available, these calls block unless the socket is set to nonblocking in which case (-1) is returned with errno set to EWOULDBLOCK. INPUTS s - a socket descriptor. buf - the buffer into which the incoming data will be placed. len - the size of the buffer. flags - select options (MSG_OOB, MSG_PEEK). from - a pointer to a sockaddr structure. fromlen - Length of the 'from' buffer. msg - pointer to a struct msghdr, defined in "sys/socket.h." RESULT numbytes - number of bytes read if successful else -1. NOTES 'fromlen' is passed with the length of the 'from' buffer. If 'from' is non-zero, the structure will be filled with the source address and fromlen will be filled in to represent the size of the actual address stored in 'from'. SEE ALSO send(), socket(), connect(), bind(), listen(), accept() socket.library/select socket.library/select NAME select -- Examines specified sockets' read, write or exception status. SYNOPSIS num = select( numfds, readfds, writefds, exceptfds, timeout ) D0 D0 A0 A1 A2 D1 int select( int, fd_set *, fd_set *, fd_set *, struct timeval *); FUNCTION select() examines the socket masks specified 'readfds,' 'writefds,' and 'execptfds' (see FD_SET) to see if they are ready for reading, for writing, or have an exceptional condition pending. When select() returns, the masks will have been modified so that only the "bits" for those sockets on which an event has occured are set. The total number of ready sockets is returned in 'num.' If 'timeout' is a non-NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the select blocks indefinitely. To affect a poll, the timeout argument should be nonzero, pointing to a zero valued timeval structure. As you know, busy-loop polling is a no-no on the Amiga. Any of readfds, writefds, and execptfds may be given as NULL if any of those categories are not of interest. select() should not be used with a single socket (use s_getsignal() and Wait() instead). INPUTS numfds - Maximum number of bits in the masks that represent valid file descriptors. readfds - 32 bit mask representing read file descriptors writefds - 32 bit mask representing write file descriptors exceptfds - 32 bit mask representing except file descriptors timeout - Pointer to a timeval structure which holds the maximum amount of time to wait for the selection to complete. RESULT num - The number of ready sockets, zero if a timeout occurred, -1 on error. readfds - A mask of the ready socket descriptors writefds - " " " " " exceptfds - " " " " " NOTES If a process is blocked on a select() waiting for input from a socket and the sending process closes the socket, the select notes this as an exception rather than as data. Hence, if the select is not currently looking for exceptions, it will wait forever. The descriptor masks are always modified on return, even if the call returns as the result of the timeout. The current version of this function calls selectwait() with a control-C option in the umask field. A common error is to use the socket number in which you are interested as the first argument. Use socket+1. BUGS SEE ALSO FD_SET(), selectwait(), s_getsignal() socket.library/selectwait socket.library/selectwait NAME selectwait -- select() with optional, task specific Wait() mask. SYNOPSIS num = selectwait( numfds, rfds, wfds, exfds, time, umask ) D0 D0 A0 A1 A2 D1 D2 int selectwait (int, int *, int *, int *, struct timeval *, long *); FUNCTION selectwait() is the same as select() except that it processes one additional argument, 'umask' The umask argument should contain either a NULL or a mask of the desired task-specific signal bits that will be tested along with the socket descriptors. selectwait() does a standard Exec Wait() call and adds the supplied mask value to Wait() argument. INPUTS numfds - The maximum number of bits in the masks that represent valid file descriptors. readfds - 32 bit mask representing read file descriptors writefds - 32 bit mask representing write file descriptors exceptfds - 32 bit mask representing except file descriptors timeout - A pointer to a timeval structure which holds the maximum amount of time to wait for the selection to complete. umask - A mask of the task's signal bits that will be used (in addition to the standard select() call return options) to have the call return. This can be SIGBREAKF signals, Intuition userport signals, console port signals, etc. Any mask that you would pass to the the Exec Wait() call is ok here. RESULT num - The number of ready file descriptors if successful. Zero (0) if a timeout occurred. (-1) upon error. readfds - A mask of the ready file descriptors writefds - " " " " " exceptfds - " " " " " umask - A mask of the bits in the originally passed 'umask' variable that have actually occured. EXAMPLE long umask = SIGBREAKF_CTRL_D | 1L << myport->mp_SigBit ; numfds = selectwait(n, r, w, e, time, &umask) ; if( event & SIGBREAKF_CTRL_D ) { printf("user hit CTRL-D\n") ; } if( event & 1L << myport->mp_SigBit ) { printf( "myport got a message\n" ) ; } NOTES A common error is to use the socket number in which you are interested as the first argument. Use socket+1. BUGS SEE ALSO FD_SET(), select(), s_getsignal() socket.library/send socket.library/send NAME send, sendto, sendmsg -- Send data from a socket. SYNOPSIS #include #include cc = send (s, buf, len, flags) D0 D0 A0 D1 A1 cc = sendto (s, buf, len, flags, to, to_len) D0 D0 A0 D1 D2 A1 D3 cc = sendmsg (s, msg, flags) D0 D0 A0 D1 int send (int, char *, int, int); int sendto (int, char *, int, int, struct sockaddr *, int); int sendmsg (int, struct msghdr *, int); FUNCTION send(), sendto(), and sendmsg() transmit data from a socket. send() must be used with a connect()'ed socket. sendto() can only be used with non-connect()'ed DGRAM-type sockets. sendmsg() is an advanced function. INPUTS s - socket descriptor. buf - pointer to message buffer. len - length of message to transmit. flags - 0 or MSG_OOB to send out-of-band data. to - pointer to a sockaddr containing the destination. to_len - sizeof(struct sockaddr). msg - pointer to a struct msghdr, defined in "sys/socket.h." RESULT cc - the number of bytes sent. This does not imply that the bytes were recieved. -1 is returned on a local error (errno will be set to the specific error code). Possible errors are: EBADF an invalid descriptor was used ENOTSOCK 's' is not a socket EMSGSIZE the socket requires that the message be sent atomically and the size of the message prevents that. EWOULDBLOCK requested operation would block EXAMPLE NOTES BUGS SEE ALSO recv(), socket() socket.library/setgid socket.library/setgid NAME setgid -- Set group id. SYNOPSIS #include return = setgid (gid) D0 D0 int setgid (gid_t); FUNCTION Sets the group id to the specified gid. INPUTS The gid to set the group id to. RESULT return - zero or -1 (on error). The socket.library configuration information for the group id will be updated. EXAMPLE NOTES This is an emulation of the Unix setgid() function. The Unix setegid() is equivalent to setgid() on the Amiga. Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". There is no support for multiple user IDs on a single Amiga because the Amiga OS has no concept of multiple users. I-Net 225 ONLY. BUGS SEE ALSO setuid() socket.library/setgrent socket.library/setgrent NAME setgrent - Opens or rewinds the group file. SYNOPSIS setgrent (flag) D1 void setgrent (int); FUNCTION If the file is already open the file is rewound. Otherwise the file is opened. INPUTS flag - if 'flag' is 1, calls to getgrgid() and getgrnam() will not close the file between calls. You must close the file with an endgrent(). Once set, 'flag' cannot be reset except by calling endgrent(). RESULT None. NOTES I-Net 225 ONLY. SEE ALSO endgrent(), getgrent() socket.library/sethostent socket.library/sethostent NAME sethostent -- Rewind the hosts file ("INet:db/hosts"). SYNOPSIS sethostent (flag) void sethostent (int); D1 FUNCTION This function is rarely useful. Opens the host file if necessary. Rewinds the host file if it is open. INPUTS flag - If 'flag' is 1, calls to gethostbyname() and gethostbyaddr() will not close the file between calls. You must close the file with an endhostent(). Once set, 'flag' cannot be reset except by calling endhostent(). RESULT None. EXAMPLE NOTES BUGS SEE ALSO gethostent(), gethostbyname(), gethostbyaddr(), endhostent() socket.library/setnetent socket.library/setnetent NAME setnetent -- Open or rewind the networks file. SYNOPSIS setnetent (flag) D1 void setnetent (int); FUNCTION Rewinds the network file if it is open. Opens the network file if it was not open. INPUTS flag - if 'flag' is 1, calls to getnetbyname() and getnetbyaddr() will not close the file between calls. You must close the file with an endnetent(). Once set, 'flag' cannot be reset except by calling endnetent(). RESULT None. EXAMPLE NOTES BUGS SEE ALSO getnetent(), getnetbyname(), getnetbyaddr(), endnetent() socket.library/setprotoent socket.library/setprotoent NAME setprotoent -- Open or rewind the protocols file. SYNOPSIS setprotoent (flag) void setprotoent (int); D1 FUNCTION This function is rarely useful. Opens the protocols file if necessary. Rewinds the protocols file if it is open. INPUTS flag - if 'flag' is 1, calls to getprotobyname() and getprotobynumber() will not close the file between calls. You must close the file with an endprotoent(). Once set, 'flag' cannot be reset except by calling endprotoent(). RESULT None. EXAMPLE NOTES BUGS SEE ALSO getprotoent(), endprotoent(), getprotobyname(), getprotobynumber() socket.library/setpwent socket.library/setpwent NAME setpwent - Opens or rewinds the password file. SYNOPSIS setpwent (flag) D1 void setpwent (int); FUNCTION If the password file is already open, it is reset to the beginning. Otherwise, it is opened. INPUTS flag - if 'flag' is 1, calls to getpwuid() and getpwnam() will not close the file between calls. You must close the file with an endpwent(). Once set, 'flag' cannot be reset except by calling endpwent(). RESULT None. SEE ALSO endpwent(), getpwent() socket.library/setservent socket.library/setservent NAME setservent -- Open or rewind the services file. SYNOPSIS setservent (flag) D1 void setservent (int); FUNCTION This function is rarely useful. Opens the services file if necessary. Rewinds the services file if it is open. INPUTS flag - if 'flag' is 1, calls to getservbyport() and getservbyname() will not close the file between calls. You must close the file with an endservent(). Once set, 'flag' cannot be reset except by calling endservent(). EXAMPLE NOTES BUGS SEE ALSO getservent(), endservent() socket.library/setsockopt socket.library/setsockopt NAME setsockopt -- Set socket options. SYNOPSIS return = setsockopt (s, level, optname, optval, optlen) D0 D0 D1 D2 A0 D3 int setsockopt (int, int, int, char *, int); FUNCTION Sets the option specified by 'optname' for socket 's.' This is an advanced function. See the "sys/socket.h" header and your favorite TCP/IP reference for more information on options. INPUTS s - socket descriptor. level - protocol level. Valid levels are: IPPROTO_IP IP options IPPROTO_TCP TCP options SOL_SOCKET socket options optname - option name. optval - pointer to the buffer with the new value. optlen - size of 'optval' (in bytes). RESULT return - 0 if successful else -1 (errno will contain the specific error). EXAMPLE int on = 1; setsockopt( s, SOL_SOCKET, SO_DEBUG, &on, (int) sizeof (on)); NOTES BUGS SEE ALSO getsockopt() socket.library/setuid socket.library/setuid NAME setuid -- Set user id. SYNOPSIS #include return = setuid (uid) D0 D0 int setuid (uid_t); FUNCTION Sets the user id to the specified uid, if the uid is valid. INPUTS The uid to set the user id to. RESULT return - zero or -1 (on error). The uid must be present in INet:db/passwd for the call to be valid. The socket.library configuration information for the uid and the username will be updated. EXAMPLE NOTES This is an emulation of the Unix setuid() function. The Unix seteuid() is equivalent to setuid() on the Amiga. Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". There is no support for multiple user IDs on a single Amiga because the Amiga OS has no concept of multiple users. I-Net 225 ONLY. BUGS SEE ALSO setgid() socket.library/setup_sockets socket.library/setup_sockets NAME setup_sockets -- Initialize global data for sockets. SYNOPSIS retval = setup_sockets (max_sockets, errnop); D0 D1 A0 ULONG setup_sockets (UWORD, int *); FUNCTION This function initializes the MAXSOCKS global variable, optionally sets the library error pointer to the application's errno, and allocates two signal bits (SIGIO and SIGURG). This should be called immediately after an OpenLibrary(). As of socket.library version 6.24, "errnop" may be NULL, and the library will use an internal error pointer safely. If 'max_sockets' is greater than FD_SETSIZE, or two signal bits cannot be allocated, setup_sockets() will return false. FD_SETSIZE is currently 128 (see ). setup_sockets() should not be called more than once in a program, especially if there are already open sockets. INPUTS max_sockets - maximum number of sockets that can be open at once. errno - pointer to the global int 'errno.' RESULT retval - TRUE on success, FALSE on failure. NOTES If you are using a language other than C, you must pass in a pointer to a variable that will hold the error numbers. In SAS C, errno is a global in c.o. If you don't link with c.o you will have to declare errno locally. Allocation of 'socks' array was moved to library initialization code. Since the total array size only reaches 512 bytes (with FD_SETSIZE of 128), its not big enough to worry about. We simply allocate the max size, and just use the 'maxsocks' parameter for program specific range checks. The library's internal error pointer is not currently visible outside of the library. For any visibility to errors, the programmer should pass a pointer to a local variable. BUGS SEE ALSO cleanup_sockets() socket.library/shutdown socket.library/shutdown NAME shutdown -- Shut down part of a full-duplex connection. SYNOPSIS return = shutdown (s, how) D0 D0 D1 int shutdown (int, int); FUNCTION Sockets are normally terminated by using just s_close(). However, s_close() will attempt to deliver any data that is still pending. Further, shutdown() provides more control over how a connection is terminated. You should eventually use s_close() on all sockets you own, regardless of what shutdown() is done on those sockets. INPUTS s - socket descriptor. how - 'how' can be one of the following: 0 disallow further receives 1 disallow further sends 2 disallow further sends and receives RESULT return - 0 if successful else -1 (errno will contain the specific error). EXAMPLE NOTES BUGS SEE ALSO s_close() socket.library/socket socket.library/socket NAME socket -- Create an endpoint for communication. SYNOPSIS s = socket (family, type, protocol) D0 D0 D1 D2 int socket (int, int, int); FUNCTION socket() returns a socket descriptor for a socket with . INPUTS family - This specifies an address format with which addresses specified in later operations using socket should be interpreted. type - Specifies the semantics of communication. protocol - Specifies a particular protocol to be used with the socket. RESULT s - Returns a (-1) upon failure ; a socket descriptor upon success. NOTES This function assumes a successful call to 'setup_sockets()' has already occured. SEE ALSO socket.library/strerror socket.library/strerror NAME strerror - Returns a pointer to an error message. SYNOPSIS #include error = strerror (error_number) D0 D1 char *strerror (int); FUNCTION The strerror() function maps the error number to a error message. INPUTS error_number - usually the value of errno. RESULT error - pointer to the error message. NOTES This function should eventually be localized. SEE ALSO , perror() socket.library/syslog socket.library/syslog NAME syslogA - log system messages SYNOPSIS error = syslogA (priority, message, argarray ) D0 D0 A0 A1 int syslogA (int, char *, int *); error = syslog (priority, message, ...) int syslog (int, char *, ...); FUNCTION syslog() writes the 'message' argument to a console window and/or a specified file. The priority field is used to determine which, if any, of the above options is used. This function is compatible with the UNIX syslog() function, taking RawDoFmt()-style arguments. Basically, this is a wrapper for the above s_syslog() function, taking care of formatting the string before sending it. A newline is added to the end of the formatted string if not already present. NOTES I-Net 225 ONLY. BUGS none known SEE ALSO inet.config (in the I-Net 225 manual) socket.library/s_close socket.library/s_close NAME s_close -- Close a socket. SYNOPSIS status = s_close (socket); D0 D0 int s_close (int); FUNCTION This function closes a socket. INPUTS unit - socket number. RESULT status - 0 if successful, else -1. EXAMPLE NOTES s_close() must always be used to close a socket. This shared library does not know about filehandles or file descriptors. BUGS SEE ALSO socket() socket.library/s_crypt socket.library/s_crypt NAME s_crypt -- Password encryption SYNOPSIS rslt = s_crypt (buffer, password, username) D0 A0 A1 A2 STRPTR s_crypt (STRPTR, STRPTR, STRPTR); FUNCTION This function takes a buffer of 32 characters in length, an unencrypted password and the user's name (as known to the host system) and returns an encrypted password in the passed buffer. This is a one-way encryption. Normally, the user's encrypted password is stored in a file for future password comparison. INPUTS buffer - a pointer to a buffer 32 bytes in length. password - a pointer to an unencrypted password string. username - a pointer to the user's name. RESULT A pointer to buffer on success, NULL on failure. EXAMPLE NOTES If a library file of 'Inet:libs/password.library' exists, the 'make_password()' entry point of that library will be called to generate the encrypted password. Otherwise, the old, standard password routine compatible with that used by the AS225 package will be called instead, for backwards compatibility. I-Net 225 ONLY. Not available in Surfer. BUGS SEE ALSO password.library/make_password socket.library/s_dev_func socket.library/s_dev_func NAME s_dev_func -- set device function SYNOPSIS s_dev_func (u_long (*function)(int)); A0 D0 void s_dev_func (u_long (*function) (int)) FUNCTION This function is intended to assist in the building of Unix compatibility libraries. The function callback that is specified when calling s_dev_func() will be utilized to determine valid numbers that can be assigned as sockets (to avoid collision with file descriptors in user programs). For SAS/C 6.x, the routine should be __chkufb(). For DICE 3.0, the routine should be __getfh(). Before assigning a socket identifier, socket.library will call this routine with a potential socket number. If it returns a zero value, socket.library will assign the next socket opened that potential number. INPUTS function - pointer to a function as described above EXAMPLE NOTES This is a kludge to get around some of the problems caused because a socket is not a file descriptor or a filehandle. If you don't understand why this function is here, you probably don't need it. I-Net 225 ONLY. socket.library/s_dev_list socket.library/s_dev_list NAME s_dev_list -- set device list SYNOPSIS s_dev_list (res, size); D0 D1 void s_dev_list (u_long, int); FUNCTION This function is intended to assist in the building of Unix compatibility libraries. s_dev_list() is passed a pointer to an array that can be used to tell the socket library which socket numbers should not be used. The socket library will not create a socket number 'X' if reserved[X] is set. The socket library will never change the contents of the reserved array. This function is compatible with SAS/C 5.x and before. For current releases of SAS/C, and for DICE, you should use s_dev_func() instead. INPUTS res - pointer to device table size - size of each entry in the device table EXAMPLE NOTES This is a kludge to get around some of the problems caused because a socket is not a file descriptor or a filehandle. If you don't understand why this function is here, you probably don't need it. socket.library/s_dup socket.library/s_dup NAME s_dup -- duplicate a socket descriptor SYNOPSIS status = s_dup (oldfd); D0 D0 int s_dup (int); FUNCTION This function creates a copy of the socket oldfd. s_dup() is used to create a copy of the socket oldfd. When successful, the sockets may then be used interchangeably to refer to the same stream. s_dup() will return the lowest available unused descriptor number. INPUTS oldfd - socket descriptor to copy. RESULT status - number of the new socket descriptor, if successful; -1 if not successful. EXAMPLE NOTES If oldfd is less than zero, greater than the maximum allowed socket (per setup_sockets()), or not currently open, EBADF will be returned in errno. If there are no more available socket descriptions, EMFILE will be returned in errno. I-Net 225 ONLY. BUGS SEE ALSO socket(), s_dup2() socket.library/s_dup2 socket.library/s_dup2 NAME s_dup2 -- duplicate a socket descriptor SYNOPSIS status = s_dup2 (oldfd, newfd); D0 D0 D1 int s_dup2 (int, int); FUNCTION This function creates a copy of the socket oldfd, and assigns the descriptor number indicated by newfd. s_dup2() is used to create a copy of the socket oldfd. When successful, the sockets may then be used interchangeably to refer to the same stream. INPUTS oldfd - socket descriptor to copy. newfd - the new socket descriptor number. RESULT status - number of the new socket descriptor, if successful; -1 if not successful. EXAMPLE NOTES If oldfd is less than zero, greater than the maximum allowed socket (per setup_sockets()), or not currently open, EBADF will be returned in errno. If newfd is less than zero or greater than the maximum allowed socket (per setup_sockets()) EBADF will be returned in errno. If newfd is open, it will be closed. I-Net 225 ONLY. BUGS SEE ALSO socket(), s_dup() socket.library/s_errno socket.library/s_errno NAME s_errno - return value of library error number SYNOPSIS retval = s_errno (); D0 int s_errno (void); FUNCTION This function returns the current error value in the library; whether the pointer set up by setup_sockets() was external or internal. INPUTS None. RESULT None. NOTES I-Net 225 ONLY. Not available in Surfer. BUGS SEE ALSO setup_sockets() socket.library/s_getsignal socket.library/s_getsignal NAME s_getsignal -- Get a network signal bit. SYNOPSIS signal = s_getsignal (type); D0 D1 BYTE s_getsignal (UWORD); FUNCTION This function returns a socket signal. The socket signal can be used to Wait() on an event for the shared socket library. The following signal types are supported: SIGIO This signal indicates a socket is ready for asynchronous I/O. This signal will be sent only if the socket has been set to async by calling ioctl() with a command of FIOASYNC. SIGURG This signal indicates the presence of urgent or out-of-band data on a TCP socket. INPUTS type - SIGIO or SIGURG. RESULT signal - signal bit (0..31) or -1 if 'type' was invalid. EXAMPLE NOTES The SIGIO signal will only be set for sockets on which FIOASYNC has been set (with s_ioctl or s_setsockopts.) BUGS SEE ALSO s_ioctl(), select(), selectwait() socket.library/s_inherit socket.library/s_inherit NAME s_inherit -- inherit a socket SYNOPSIS s = s_inherit (sockptr); D0 D1 int s_inherit (void *); FUNCTION This function along with s_release() provide a way to pass a socket from one process to another. s_inherit() will attach a socket that has been released to your process. Use instead of socket() when another process hands you a socket. INPUTS sockptr - really a pointer to an internal socket structure RESULT s - socket descriptor (-1 on failure) EXAMPLE void main (void) { int errno, s; long opts [OPT_COUNT]; struct RDargs *rdargs; memset ((char *) opts, 0, sizeof (opts)); rdargs = ReadArgs (TEMPLATE, opts, NULL); if ((SockBase = OpenLibrary ("inet:libs/socket.library", 1)) == NULL) { goto exit1; } setup_sockets (5, &errno); / * now get our socket * / s = s_inherit ((void *)*(long *) opts [OPT_SOCKPTR]); NOTES Use with caution. Calling s_inherit() with an invalid sockptr will cause serious problems. BUGS Not safe if an invalid pointer is passed. SEE ALSO s_release() socket.library/s_ioctl socket.library/s_ioctl NAME s_ioctl -- Control socket options. SYNOPSIS return = s_ioctl (s, cmd, data) D0 D0 D1 A0 int s_ioctl (int, int, char *); FUNCTION Manipulates device options for a socket. INPUTS s - socket descriptor. cmd - command. data - data. The following commands are supported: command description data points to ------- ----------- -------------- FIONBIO set/clear nonblocking I/O int FIOASYNC set/clear async I/O int FIONREAD get number of bytes to read int SIOCATMARK at out-of-band mark? int SIOCSPGRP set process group int SIOCGPGRP get process group int SIOCADDRT add route struct rtentry SIOCDELRT delete route struct rtentry SIOCGIFCONF get ifnet list struct ifconf SIOCGIFFLAGS get ifnet flags struct ifreq SIOCSIFFLAGS set ifnet flags struct ifreq SIOCGIFMETRIC get IF metric struct ifreq SIOCSIFMETRIC set IF metric struct ifreq SIOCGARP get ARP entry struct arpreq SIOCSARP get ARP entry struct arpreq SIOCDARP delete ARP entry struct arpreq For more information, see a Unix reference manual. RESULT return - 0 on success, else -1 (errno will be set to the specific error code). EXAMPLE int one = 1; ioctl (s, FIOASYNC, (char *) &one); NOTES The standard Unix ioctl() function operates on both files and sockets. Some compiler vendors may supply an ioctl() function. Because of this, and because this function works only with sockets, it has been renamed to s_ioctl(). BUGS SEE ALSO setsockopts() socket.library/s_release socket.library/s_release NAME s_release -- release a socket SYNOPSIS sockptr = s_release (s); D0 D1 void *s_release (int); FUNCTION This function along with s_inherit() provide a way to pass a socket from one process to another. s_release(s) will "detach" socket s from the current process. Your process will no longer know about the socket. You can not call s_close() on a socket you have released because it is no longer owned until it is s_inherit()ed. Once socket 's' is released, the socket descriptor 's' will be reused. INPUTS s - socket descriptor RESULT sockptr - really a pointer to an internal socket structure NULL on failure EXAMPLE sockptr = s_release (s); / * start a new program and pass socket on command line * / sprintf (cmdbuf, "run >nil: %s %ld", cmd_name, sockptr); Execute (cmdbuf, 0, 0); NOTES Use with caution. Don't release a socket unless another process will s_inherit() it. You _really_ don't want to do this to a socket which has had a s_dup() or s_dup2() executed against it, without being _very_ careful. BUGS SEE ALSO s_inherit() socket.library/s_syslog socket.library/s_syslog NAME s_syslog - log system messages SYNOPSIS error = s_syslog (priority, message) D0 D0 A0 int s_syslog (int, char *); FUNCTION s_syslog() writes the 'message' argument to a console window and/or a specified file. The priority field is used to determine which, if any, of the above options is used. The file "inet:s/inet.config" contains the optional fields: filepri - msgs w/pri >= filepri are sent to file. windowpri - msgs w/pri >= windowpri are sent to window. syslogfilename - the path/name of the file for filepri messages. syslogconsole - a console window definition Example: (Note: this is the exact format to use in the 'inet:s/inet.config' file.) filepri=5 windowpri=3 syslogfilename=t:foobar syslogconsole=CON:0/0/600/70/ SYSLOG /AUTO/CLOSE These entries tell s_syslog how to deal with the messages it is sent. Note that the smaller the priority number, the greater it's priority. Therefore, a message of priority 3 is of greater importance than a message of priority 4. If you do not add these fields to your 'inet:s/inet.config' file, the default values will be used. The default values are: windowpri = 4 filepri = 3 syslogfilename = RAM:syslog.dat syslogconsole = CON:0/0/600/70/ SYSLOG /AUTO/CLOSE/INACTIVE/WAIT The above values mean: 1. A message sent with a priority >= 4 (4,3,2,1,0) will be sent to BOTH the console window and the file 'RAM:syslog.dat'. 2. A message sent with a priority >= 3 (3,2,1,0) will be sent to ONLY the console window. 3. A message sent with a priority < 4 (5,6,7,8) will be ignored. INPUTS pri - an integer value between 0-7 message - a string to be written to the console window and/or the syslog file. RESULT error - 0 (zero) is returned if everything went well. - -1 is returned if anything went wrong. If an error has occurred, you need to examine your errno value to determine just what went wrong. It is possible, for example, to have a write to the console window succeed while a write of the same message to the file failed. The various error values that occur during the syslog operation are OR'd together and returned in 'errno'. See the file "sys/syslog.h" for the values. Example: #include ... extern int errno; int error; error = s_syslog (5, "This is a test\n"); if (error == -1) { if (errno & SYSLOGF_WINDOWOPEN) { printf ("Could not open syslog window\n"); } if (errno & SYSLOGF_FILEWRITE) { printf ("Could not write to syslog file\n"); } } NOTES 1. s_syslog () will clear the global errno value with each call. 2. Use syslog () to send printf-style arguments (at a higher overhead). 3. The maximum length of a syslogfilename line in inet.config is 256 characters. This includes the 'syslogfilename=' portion of the line. maxlen (path/filename) = 256 - len ("syslogfilename=") Similarly for syslogconsole. BUGS none known SEE ALSO inet.config (in the I-Net 225 manual) socket.library/umask socket.library/umask NAME umask -- get and set user file creation mask SYNOPSIS #include umask = umask (cmask) D0 D0 mode_t umask (mode_t); FUNCTION The umask() function sets the file creation mask to 'cmask' and returns the old value of the mask. RESULT -1 will be returned and an error message will be displayed if there is a problem reading the current configuration. EXAMPLE NOTES Amiga filesystems, of course, will not use this file creation mask. We use it for NFS, and provide it in case you can think of something to use it for. The new mask value is not saved to the configuration file. It will be reset when the machine is rebooted. Currently, configuration information is stored in memory in a configuration structure. This structure is initialized when the network functions are started, and the data comes from "INet:s/inet.config". BUGS SEE ALSO getumask()