Amiga Developer CD v1.2

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Developer CD v1.2 / amidev_cd_12.iso / devcon / milan_1991 / devcon91.2 / network / socket / socket.doc < prev

Wrap

Text File | 1992-09-01 | 73KB | 2,888 lines

TABLE OF CONTENTS background socket.library/accept socket.library/bind socket.library/cleanup_sockets socket.library/connect socket.library/endhostent socket.library/endnetent socket.library/endprotoent socket.library/endpwent socket.library/endservent socket.library/FD_SET socket.library/get_tz socket.library/getdomainname socket.library/getgid 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/inet_addr 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/s_close socket.library/s_getsignal socket.library/s_ioctl socket.library/select socket.library/selectwait socket.library/send socket.library/sethostent socket.library/setnetent socket.library/setprotoent socket.library/setpwent socket.library/setservent socket.library/setsockopt socket.library/setup_sockets socket.library/shutdown socket.library/socket socket.library/strerror socket.library/syslog socket.library/umask background 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. The link socket library that received very limited alpha distribution is obsolete. 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 or from our obsolete link library), 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 In case you're wondering, our old link library was compiler-specific and included the compiler's library code for read(), write(), close() and ioctl(). On Un*x machines, these 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 for 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 <exec/types.h> #include <exec/libraries.h> #include <exec/execbase.h> #include <dos/dos.h> #include <proto/all.h> #include <sys/types.h> #include <sys/socket.h> #include <stdio.h> #include <errno.h> /* the next two lines must always be here */ #include <ss/socket.h> struct Library *SockBase ; /* this is the maximum number of sockets that you want */ #define MAXSOCKS 10 main() { if((SockBase = OpenLibrary( "inet:libs/socket.library", 1L )) == 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 © 1991 Commodore-Amiga, Inc. All Rights Reserved. The shared socket library was written by Martin Hunt. Dale Larson helped with the documentation and testing. Parts of this shared socket library and the associated header files are derived from code which is: Copyright (c) 1983 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/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/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/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. BUGS SEE ALSO setup_sockets() 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/endhostent socket.library/endhostent NAME endhostent -- Closes the hosts file ("inet:s/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. 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 <sys/types.h> 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/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. An error requester is displayed on error. NOTES THIS IS AN AMIGA-ONLY FUNCTION. Currently the configuration information is stored in memory in a configuration structure. If this structure cannot be found, it will be initialized by reading in inet:s/inet.config. This may change in the future. 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/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 the configuration information is stored in memory in a configuration structure. If this structure cannot be found, it will be initialized by reading in inet:s/inet.config. This may change in the future. BUGS SEE ALSO socket.library/getgid socket.library/getgid NAME getgid -- Get group id. SYNOPSIS #include <sys/types.h> gid = getgid() gid_t getgid (void); FUNCTION returns the user's group id INPUTS None. RESULT gid - group ID or -1 (on error). An error requester will be displayed if there is a problem reading the current configuration. EXAMPLE NOTES This is an emulation of the Unix getgid() function. 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, the configuration information is stored in memory in a configuration structure. If this structure cannot be found, it will be initialized by reading in inet:s/inet.config. This may change in the future. BUGS SEE ALSO getgroups(), getuid() socket.library/getgroups socket.library/getgroups NAME getgroups -- Get group access list. SYNOPSIS #include <sys/types.h> #include <sys/param.h> 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[10]; int number_of_gids; number_of_gids = getgroups(10,gids); NOTES Currently, the configuration information is stored in memory in a configuration structure. If this structure cannot be found, it will be initialized by reading in inet:s/inet.config. This may change in the future. The upper limit of groups that can be returned by getgroups() is NGROUP (in <sys/param.h>). 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 <sys/socket.h> #include <netdb.h> 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. In the future, this function will look beyond just 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 protocol 'addr.' NULL on EOF or failure to open protocols 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 <sys/socket.h> #include <netdb.h> 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. In the future, this function will look beyond just 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 protocol 'name.' NULL on EOF or failure to open protocols 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:s/hosts"). SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netdb.h> 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 Un*x compatibility and even Un*x 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 for next protocol. NULL on EOF or failure to open protocols 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 character array. length - size of character array. RESULT return - 0 if successful, else -1. The only reason for failure will be if the configuration file is unavailable, in which case an error requester will be displayed. NOTES Currently, the configuration information is stored in memory in a configuration structure. If this structure cannot be found, it will be initialized by reading in inet:s/inet.config. This may change in the future. 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, the configuration information is stored in memory in a configuration structure. If this structure cannot be found, it will be initialized by reading in inet:s/inet.config. This may change in the future. There is no support for multiple user names 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 <netdb.h> 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 <netdb.h> 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 <netdb.h> 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 <netdb.h> 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 <netdb.h> 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 <netdb.h> 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 Un*x 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. 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 <pwd.h> 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. 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 <pwd.h> 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. 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 <netdb.h> 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 <netdb.h> 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 <netdb.h> 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 Un*x 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 <sys/types.h> uid = getuid() D0 uid_t getuid (void); FUNCTION Returns the user id. INPUTS None. RESULT uid - user ID or -1 (on error). An error requester will be displayed if there is a problem reading the current configuration. EXAMPLE NOTES This is an emulation of the Unix getuid() function. geteuid() is equivalent to getuid() on the Amiga. Currently, the configuration information is stored in memory in a configuration structure. If this structure cannot be found, it will be initialized by reading in inet:s/inet.config. This may change in the future. 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 <sys/types.h> 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, the configuration information is stored in memory in a configuration structure. If this structure cannot be found, it will be initialized by reading in inet:s/inet.config. This may change in the future. BUGS SEE ALSO umask() socket.library/inet_addr socket.library/inet_addr NAME inet_addr -- make internet address from string SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> 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_lnaof socket.library/inet_lnaof NAME inet_lnaof -- give the local network address SYNOPSIS #include <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> 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 <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> 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 <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> 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 <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> 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 <sys/types.h> #include <sys/socket.h> #include <netinet/in.h> 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. 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. The current mechanism is in transition and is guaranteed to change. BUGS SEE ALSO socket.library/recv socket.library/recv NAME recv, recvfrom, recvmsg -- Receive a message from a socket. SYNOPSIS #include <sys/types.h> #include <sys/socket.h> 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/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_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_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/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 <sys/types.h> #include <sys/socket.h> 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/sethostent socket.library/sethostent NAME sethostent -- Rewind the hosts file ("inet:s/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 file is already open the file is rewound. Otherwise the file 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/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 global variables, sets the library errno to point to the application's errno, and allocates signals. This should always be called immediately after an OpenLibrary(). The only reason this initialization is not done automatically is because a pointer to errno must be passed in. 'max_sockets' must be less than FD_SETSIZE. INPUTS max_sockets - maximum number of sockets that can be open at once. (4 bytes are allocated for each socket.) errno - pointer to the global int 'errno.' RESULT retval - TRUE on success, FALSE on failure. If 'max_sockets' is greater than FD_SETSIZE, setup_sockets() will fail. FD_SETSIZE is currently 128 (see <sys/types.h>) 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 lc.lib. If you don't link with lc.lib you will have to declare errno locally. 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 semantice 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 Unlike the linkable socket library, this function assumes that you have already made a succesful call to 'setup_sockets()'. SEE ALSO socket.library/strerror socket.library/strerror NAME strerror - Returns a pointer to an error message. SYNOPSIS #include <string.h> error = strerror( error_number ) D0 D1 char *strerror( int ); FUNCTION The strerror() function maps the error number to a language- dependent Unix 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 <errno.h>, perror() socket.library/syslog socket.library/syslog NAME syslog - log system messages SYNOPSIS error = syslog( priority, message ) D0 A0 D0 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. 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. Example: (Note: this is the exact format to use in the 'inet:s/inet.config' file.) filepri=5 windowpri=3 syslogfilename="t:foobar" These entries tell 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 you 'inet:s/inet.config' file, the default values will be used. The default values are: windowpri = 4 filepri = 3 syslogfilename = "ram:syslog.dat" 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<sys/syslog.h> ... extern int errno ; int error ; error = 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. syslog() will clear the global errno value with each call. 2. Unlike the Unix syslog() function, the Amiga version does not handle printf-style arguments. This will need to be handled in the application. 3. The maximum length of a syslogfilename line in inet.config is 127 characters. This includes the 'syslogfilename=' portion of the line. maxlen(path/filename) = 127 - len( "syslogfilename=" ) BUGS none known SEE ALSO inet.config (in the AS225 manual) socket.library/umask socket.library/umask NAME umask -- get and set user file creation mask SYNOPSIS #include <sys/types.h> 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, the configuration information is stored in memory in a configuration structure. If this structure cannot be found, it will be initialized by reading in inet:s/inet.config. This may change in the future. BUGS SEE ALSO getumask()