# MAN3 MAN3 (3) Section 3 of the Manual describes C library routines, and is primarily intended for programmers. The sections of the manual are: Section 1: User commands Section 2: System calls --> Section 3: C library Section 4: File formats Section 5: Miscellaneous Section 6: Games Section 7: Special files (devices) Section 8: Maintenance procedures # curses Definitions in /usr/include/curses.h extern char termcap[]; extern char tc[]; extern char *ttytype; extern char *arp; extern char *cp; extern char *cl; extern char *cm; extern char *so; extern char *se; extern char row, col, mode; extern char str[]; void addstr(); void clear(); void clrtobot(); void clrtoeol(); void endwin(); void fatal(); char inch(); void initscr(); void move(); void printw(); void outc(); void refresh(); void standend(); void standout(); void touchwin(); # libc Source files included in /usr/lib/libc.a _dup.s _exit.s abort.s abs.s access.s adi.s alarm.s amoeba.s and.s assert.s atoi.s atol.s bcmp.s bcopy.s blm.s brk.s brksize.s bsearch.s bzero.s call.s catchsig.s chdir.s chmod.s chown.s chroot.s cii.s cleanup.s close.s closedir.s cmi4.s cms.s cmu4.s com.s creat.s crypt.s csa2.s csb2.s ctermid.s ctime.s ctype.s curses.s cuserid.s cuu.s doprintf.s dup.s dup2.s dvi4.s dvu4.s errno.s exec.s execlp.s exg.s exit.s fakfp.s fat.s fclose.s fcntl.s fdopen.s fflush.s ffs.s fgetc.s fgets.s fopen.s fork.s fpathconf.s fprintf.s fputc.s fputs.s fread.s freopen.s fseek.s fstat.s ftell.s fwrite.s getcwd.s getdents.s getegid.s getenv.s geteuid.s getgid.s getgrent.s getlogin.s getopt.s getpass.s getpid.s getppid.s getpwent.s gets.s getuid.s getutil.s gto.s gtty.s iaar.s ilar.s index.s inn.s ioctl.s ior.s isar.s isatty.s itoa.s kill.s lar2.s lfr6.s lfr8.s link.s lock.s loi.s lrand.s lsearch.s lseek.s malloc.s memccpy.s memchr.s memcmp.s memcpy.s memmove.s memset.s message.s mkdir.s mkfifo.s mknod.s mktemp.s mli4.s mon.s mount.s nlist.s nop.s open.s opendir.s pathconf.s pause.s peekpoke.s perror.s pipe.s popen.s portio.s printdat.s printk.s prints.s ptrace.s putenv.s puts.s qsort.s rand.s rck.s read.s readdir.s regexp.s regsub.s rename.s ret6.s ret8.s retarea.s return.s rewinddir.s rindex.s rmdir.s rmi4.s rmu4.s sar2.s sbi.s scanf.s seekdir.s sendrec.s set.s setbuf.s setgid.s setjmp.s setuid.s signal.s sincos.s sleep.s sprintf.s stat.s stb.s stderr.s sti.s stime.s stop.s strcat.s strchr.s strcmp.s strcoll.s strcpy.s strcspn.s strerror.s strhp.s strlen.s strncat.s strncmp.s strncpy.s strpbrk.s strrchr.s strspn.s strstr.s strtok.s strtol.s strtoul.s strxfrm.s stty.s swab.s sync.s sysconf.s syslib.s system.s telldir.s termcap.s time.s times.s tmpnam.s trp.s ttyname.s umask.s umount.s ungetc.s uniqport.s unknown.s unlink.s utime.s vars.s vectab.s vsprintf.s wait.s rite.s xor.s # stddef Definitions in /usr/include/stddef.h typedef int ptrdiff_t; typedef unsigned int size_t; typedef char wchar_t; # stdio Definitions in /usr/include/stdio.h extern struct _io_buf { int _fd; int _count; int _flags; char *_buf; char *_ptr; } *_io_table[20]; typedef unsigned size_t; int getc (); int getchar (); int putc (); int putchar (); int feof (); int ferror (); void clearerr (); struct _io_buf *fopen (); struct _io_buf *freopen (); int fflush (); int fclose (); int fgetpos (); int fsetpos (); long ftell (); int fseek (); void rewind (); int fgetc (); int fputc (); size_t fread (); size_t fwrite (); int getw (); int putw (); char *gets (); char *fgets (); int puts (); int fputs (); int ungetc (); void printf (); void fprintf (); char *sprintf (); int vprintf (); int vfprintf (); char *vsprintf (); int scanf (); int fscanf (); int sscanf (); void setbuf (); int setvbuf (); int rename (); int remove (); void perror (); char * tmpnam (); struct _io_buf * tmpfile (); int unlink (); char * ctermid (); char * cuserid (); struct _io_buf *fdopen (); int fileno (); extern void (*__cleanup)(); void _doprintf(); int _doscanf(); void prints(); extern struct _io_buf *fopen(); extern struct _io_buf *freopen(); extern long ftell(); extern char *fgets(); extern char *gets(); # stdlib Definitions in /usr/include/stdlib.h typedef struct { int quot, rem; } div_t; typedef struct { long quot, rem; } ldiv_t; typedef unsigned int size_t; typedef char wchar_t; void abort(); int abs(); int atexit(); double atof(); int atoi(); long atol(); void *calloc(); div_t div(); void exit(); void free(); char *getenv(); long labs(); ldiv_t ldiv(); void *malloc(); int mblen(); size_t mbstowcs(); int mbtowc(); int rand(); void *realloc(); void srand(); double strtod(); long strtol(); int system(); size_t wcstombs(); int wctomb(); void *bsearch(); void qsort(); unsigned long int strtoul(); # string Definitions in /usr/include/string.h typedef unsigned int size_t; void *memcpy(); void *memmove(); char *strcpy(); char *strcpy(char *s1, *s2) copy s2 to s1, regresa s1 char *strncpy(); char *strncpy(char *s1, *s2; int n) copy up to n charactters from s2 to s1, return s1 char *strcat(); char *strcat(char *s1, *s2) concatenate s2 on s1, return result in s1 char *strncat(); char *strncat(char *s1, *s2; int n) append up to n characters from s2 on s1, return s1 int memcmp(); int strcmp(); int strcmp(char *s1, *s2) returns 0 if s1 = s2 -1 if s1 < s2 1 if s1 > s2 int strcoll(); int strncmp(); int strncmp(char *s1, *s2; int n) like strcmp, but compare only n characters size_t strxfrm(); void *memchr(); char *strchr(); char *strchr(char *s; char c) return pointer to first occurence of c in s, or NULL size_t strcspn(); char *strpbrk(); char *strrchr(); char *strrchr(char *s; char c) return pointer to last occurence of c in s, or NULL size_t strspn(); char *strstr(); char *strtok(); void *memset(); char *strerror(); size_t strlen(); These functions not provided in Minix v. 1.5, written by asw, can be found in file /usr/include/string2.h int strpos(char *s, char c) returns index of position of c in s or -1 if not found char *strnrtcpy(char *s1, *s2; int i) copy right substring of s2 to s1, starting with index i, returns s1 ref: Muldner y Steele pp. 559-560 # byteorder NAME htonl, htons, ntohl, ntohs - convert values between host and network byte order SYNOPSIS #include netlong = htonl(hostlong); u_long netlong, hostlong; netshort = htons(hostshort); u_short netshort, hostshort; hostlong = ntohl(netlong); u_long hostlong, netlong; hostshort = ntohs(netshort); u_short hostshort, netshort; DESCRIPTION These routines convert 16 and 32 bit quantities between network byte order and host byte order. On machines such as the SUN these routines are defined as null macros in the include file < netinet/in.h >. These routines are most often used in conjunction with Internet addresses and ports as returned by gethostbyname(3) and getservent(3). SEE ALSO gethostbyname(3), getservent(3) BUGS The VAX handles bytes backwards from most everyone else in the world. This is not expected to be fixed in the near future. OTHER INFO These functions are part of the Tnet library. # gethostent NAME gethostbyname, gethostbyaddr, gethostent, sethostent, endhostent, herror - get network host entry SYNOPSIS #include extern int h_errno; struct hostent *gethostbyname(name) char *name; struct hostent *gethostbyaddr(addr, len, type) char *addr; int len, type; struct hostent *gethostent() sethostent(stayopen) int stayopen; endhostent() herror(string) char *string; DESCRIPTION Gethostbyname and gethostbyaddr each return a pointer to an object with the following structure describing an internet host referenced by name or by address, respectively. This structure contains either the information obtained from the name server, named(8), or broken- out fields from a line in /etc/hosts . If the local name server is not running these routines do a lookup in /etc/hosts . 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] /* address, for backward compatibility */ The members of this structure are: h_name Official name of the host. h_aliases A zero terminated array of alternate names for the host. h_addrtype The type of address being returned; currently always AF_INET. h_length The length, in bytes, of the address. h_addr_list A zero terminated array of network addresses for the host. Host addresses are returned in network byte order. h_addr The first address in h_addr_list; this is for backward compatiblity. When using the nameserver, gethostbyname will search for the named host in the current domain and its parents unless the name ends in a dot. If the name contains no dot, and if the environment variable ``HOSTALAIASES'' contains the name of an alias file, the alias file will first be searched for an alias matching the input name. See hostname(7) for the domain search procedure and the alias file format. Sethostent may be used to request the use of a connected TCP socket for queries. If the stayopen flag is non-zero, this sets the option to send all queries to the name server using TCP and to retain the connection after each call to gethostbyname or gethostbyaddr . Otherwise, queries are performed using UDP datagrams. Endhostent closes the TCP connection. DIAGNOSTICS Error return status from gethostbyname and gethostbyaddr is indicated by return of a null pointer. The external integer h_errno may then be checked to see whether this is a temporary failure or an invalid or unknown host. The routine herror can be used to print an error message describing the failure. If its argument string is non-NULL, it is printed, followed by a colon and a space. The error message is printed with a trailing newline. h_errno can have the following values: HOST_NOT_FOUND No such host is known. TRY_AGAIN This is usually a temporary error and means that the local server did not receive a response from an authoritative server. A retry at some later time may succeed. NO_RECOVERY Some unexpected server failure was encountered. This is a non-recoverable error. NO_DATA The requested name is valid but does not have an IP address; this is not a temporary error. This means that the name is known to the name server but there is no address associated with this name. Another type of request to the name server using this domain name will result in an answer; for example, a mail-forwarder may be registered for this domain. FILES /etc/hosts SEE ALSO resolver(3), hosts(5), hostname(7), named(8) CAVEAT Gethostent is defined, and sethostent and endhostent are redefined, when libc is built to use only the routines to lookup in /etc/hosts and not the name server. Gethostent reads the next line of /etc/hosts , opening the file if necessary. Sethostent is redefined to open and rewind the file. If the stayopen argument is non-zero, the hosts data base will not be closed after each call to gethostbyname or gethostbyaddr . Endhostent is redefined to close the file. BUGS All information is contained in a static area so it must be copied if it is to be saved. Only the Internet address format is currently understood. OTHER INFO These functions are part of the Tnet library. # getnetent NAME getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent - get network entry SYNOPSIS #include struct netent *getnetent() struct netent *getnetbyname(name) char *name; struct netent *getnetbyaddr(net, type) long net; int type; setnetent(stayopen) int stayopen; endnetent() DESCRIPTION Getnetent , getnetbyname , and getnetbyaddr each return a pointer to an object with the following structure containing the broken-out fields of a line in the network data base, /etc/networks . struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ int n_addrtype; /* net number type */ unsigned long n_net; /* net number */ }; The members of this structure are: n_name The official name of the network. n_aliases A zero terminated list of alternate names for the network. n_addrtype The type of the network number returned; currently only AF_INET. n_net The network number. Network numbers are returned in machine byte order. Getnetent reads the next line of the file, opening the file if necessary. Setnetent opens and rewinds the file. If the stayopen flag is non-zero, the net data base will not be closed after each call to getnetbyname or getnetbyaddr . Endnetent closes the file. Getnetbyname and getnetbyaddr sequentially search from the beginning of the file until a matching net name or net address and type is found, or until EOF is encountered. Network numbers are supplied in host order. FILES /etc/networks SEE ALSO networks(5) DIAGNOSTICS Null pointer (0) returned on EOF or error. BUGS All information is contained in a static area so it must be copied if it is to be saved. Only Internet network numbers are currently understood. Expecting network numbers to fit in no more than 32 bits is probably naive. OTHER INFO These functions are part of the Tnet library. # getprotoent NAME getprotoent, getprotobynumber, getprotobyname, setprotoent, endprotoent - get protocol entry SYNOPSIS #include struct protoent *getprotoent() struct protoent *getprotobyname(name) char *name; struct protoent *getprotobynumber(proto) int proto; setprotoent(stayopen) int stayopen endprotoent() DESCRIPTION Getprotoent , getprotobyname , and getprotobynumber each return a pointer to an object with the following structure containing the broken-out fields of a line in the network protocol data base, /etc/protocols . struct protoent { char *p_name; /* official name of protocol */ char **p_aliases; /* alias list */ int p_proto; /* protocol number */ }; The members of this structure are: p_name The official name of the protocol. p_aliases A zero terminated list of alternate names for the protocol. p_proto The protocol number. Getprotoent reads the next line of the file, opening the file if necessary. Setprotoent opens and rewinds the file. If the stayopen flag is non-zero, the net data base will not be closed after each call to getprotobyname or getprotobynumber . Endprotoent closes the file. Getprotobyname and getprotobynumber sequentially search from the beginning of the file until a matching protocol name or protocol number is found, or until EOF is encountered. FILES /etc/protocols SEE ALSO protocols(5) DIAGNOSTICS Null pointer (0) returned on EOF or error. BUGS All information is contained in a static area so it must be copied if it is to be saved. Only the Internet protocols are currently understood. OTHER INFO These functions are part of the Tnet library. # getservent NAME getservent, getservbyport, getservbyname, setservent, endservent - get service entry SYNOPSIS #include struct servent *getservent() struct servent *getservbyname(name, proto) char *name, *proto; struct servent *getservbyport(port, proto) int port; char *proto; setservent(stayopen) int stayopen endservent() DESCRIPTION Getservent , getservbyname , and getservbyport each return a pointer to an object with the following structure containing the broken-out fields of a line in the network services data base, /etc/services . struct servent { char *s_name; /* official name of service */ char **s_aliases; /* alias list */ int s_port; /* port service resides at */ char *s_proto; /* protocol to use */ }; The members of this structure are: s_name The official name of the service. s_aliases A zero terminated list of alternate names for the service. s_port The port number at which the service resides. Port numbers are returned in network byte order. s_proto The name of the protocol to use when contacting the service. Getservent reads the next line of the file, opening the file if necessary. Setservent opens and rewinds the file. If the stayopen flag is non-zero, the net data base will not be closed after each call to getservbyname or getservbyport . Endservent closes the file. Getservbyname and getservbyport sequentially search from the beginning of the file until a matching protocol name or port number is found, or until EOF is encountered. If a protocol name is also supplied (non-NULL), searches must also match the protocol. FILES /etc/services SEE ALSO getprotoent(3), services(5) DIAGNOSTICS Null pointer (0) returned on EOF or error. BUGS All information is contained in a static area so it must be copied if it is to be saved. Expecting port numbers to fit in a 32 bit quantity is probably naive. OTHER INFO These functions are part of the Tnet library. # inet NAME inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof, inet_netof - Internet address manipulation routines SYNOPSIS #include #include #include int inet_aton(cp, pin) char *cp; struct in_addr *pin; unsigned long inet_addr(cp) char *cp; unsigned long inet_network(cp) char *cp; char *inet_ntoa(in) struct in_addr in; struct in_addr inet_makeaddr(net, lna) int net, lna; unsigned long inet_lnaof(in) struct in_addr in; unsigned long inet_netof(in) struct in_addr in; DESCRIPTION The routines inet_aton , inet_addr and inet_network interpret character strings representing numbers expressed in the Internet standard . (dotted decimal) notation. The inet_aton routine interprets the specified character string as an Internet address, placing the address into the structure provided. It returns 1 if the string was successfully interpreted, or 0 if the string is invalid. The inet_addr and inet_network functions return numbers suitable for use as Internet addresses and Internet network numbers, respectively. The routine inet_ntoa takes an Internet address and returns an ASCII string representing the address in . (dotted decimal) notation. The routine inet_makeaddr takes an Internet network number and a local network address and constructs an Internet address from it. The routines inet_netof and inet_lnaof break apart Internet host addresses, returning the network number and local network address part, respectively. All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine format integer values. INTERNET ADDRESSES Values specified using the \*(lq.\*(rq notation take one of the following forms: a.b.c.d a.b.c a.b a When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the four bytes of an Internet address. Note that when an Internet address is viewed as a 32-bit integer quantity on the VAX the bytes referred to above appear as d.c.b.a. That is, VAX bytes are ordered from right to left. When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right-most two bytes of the network address. This makes the three part address format convenient for specifying Class B network addresses as 128.net.host. When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right most three bytes of the network address. This makes the two part address format convenient for specifying Class A network addresses as net.host. When only one part is given, the value is stored directly in the network address without any byte rearrangement. All numbers supplied as parts in a . notation may be decimal, octal, or hexadecimal, as specified in the C language (i.e., a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). SEE ALSO gethostbyname(3), getnetent(3), hosts(5), networks(5), DIAGNOSTICS The constant INADDR_NONE is returned by inet_addr and inet_network for malformed requests. BUGS The value INADDR_NONE (0xffffffff) is a valid broadcast address, but inet_addr cannot return that value without indicating failure. The newer inet_aton function does not share this problem. The problem of host byte ordering versus network byte ordering is confusing. The string returned by inet_ntoa resides in a static memory area. Inet_addr should return a struct in_addr. OTHER INFO These functions are part of the Tnet library. # resolver NAME res_query, res_search, res_mkquery, res_send, res_init, dn_comp, dn_expand - resolver routines SYNOPSIS #include #include #include #include res_query(dname, class, type, answer, anslen)" char *dname; int class, type; u_char *answer; int anslen; res_search(dname, class, type, answer, anslen)" char *dname; int class, type; u_char *answer; int anslen; res_mkquery(op, dname, class, type, data, datalen, newrr, buf, buflen)" int op; char *dname; int class, type; char *data; int datalen; struct rrec *newrr; char *buf; int buflen; res_send(msg, msglen, answer, anslen) char *msg; int msglen; char *answer; int anslen; res_init() dn_comp(exp_dn, comp_dn, length, dnptrs, lastdnptr) char *exp_dn, *comp_dn; int length; char **dnptrs, **lastdnptr; dn_expand(msg, eomorig, comp_dn, exp_dn, length) char *msg, *eomorig, *comp_dn, exp_dn; int length; DESCRIPTION These routines are used for making, sending and interpreting query and reply messages with Internet domain name servers. Global configuration and state information that is used by the resolver routines is kept in the structure _res . Most of the values have reasonable defaults and can be ignored. Options stored in _res.options are defined in resolv.h and are as follows. Options are stored as a simple bit mask containing the bitwise ``or'' of the options enabled. RES_INIT True if the initial name server address and default domain name are initialized (i.e., res_init has been called). RES_DEBUG Print debugging messages. RES_AAONLY Accept authoritative answers only. With this option, res_send should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. RES_USEVC Use TCP connections for queries instead of UDP datagrams. RES_STAYOPEN Used with RES_USEVC to keep the TCP connection open between queries. This is useful only in programs that regularly do many queries. UDP should be the normal mode used. RES_IGNTC Unused currently (ignore truncation errors, i.e., don't retry with TCP). RES_RECURSE Set the recursion-desired bit in queries. This is the default. (res_send does not do iterative queries and expects the name server to handle recursion.) RES_DEFNAMES If set, res_search will append the default domain name to single-component names (those that do not contain a dot). This option is enabled by default. RES_DNSRCH If this option is set, res_search will search for host names in the current domain and in parent domains; see .IR hostname (7). This is used by the standard host lookup routine gethostbyname (3). This option is enabled by default. The res_init routine reads the configuration file (if any; see resolver(5)) to get the default domain name, search list and the Internet address of the local name server(s). If no server is configured, the host running the resolver is tried. The current domain name is defined by the hostname if not specified in the configuration file; it can be overridden by the environment variable LOCALDOMAIN. Initialization normally occurs on the first call to one of the following routines. The res_query function provides an interface to the server query mechanism. It constructs a query, sends it to the local server, awaits a response, and makes preliminary checks on the reply. The query requests information of the specified type and class for the specified fully-qualified domain name dname . The reply message is left in the answer buffer with length anslen supplied by the caller. The res_search routine makes a query and awaits a response like res_query , but in addition, it implements the default and search rules controlled by the RES_DEFNAMES and RES_DNSRCH options. It returns the first successful reply. The remaining routines are lower-level routines used by res_query . The res_mkquery function constructs a standard query message and places it in buf . It returns the size of the query, or -1 if the query is larger than buflen . The query type op is usually QUERY, but can be any of the query types defined in . The domain name for the query is given by dname . Newrr is currently unused but is intended for making update messages. The res_send routine sends a pre-formatted query and returns an answer. It will call res_init if RES_INIT is not set, send the query to the local name server, and handle timeouts and retries. The length of the reply message is returned, or -1 if there were errors. The dn_comp function compresses the domain name exp_dn and stores it in comp_dn . The size of the compressed name is returned or -1 if there were errors. The size of the array pointed to by comp_dn is given by length . The compression uses an array of pointers dnptrs to previously- compressed names in the current message. The first pointer points to to the beginning of the message and the list ends with NULL. The limit to the array is specified by lastdnptr . A side effect of dn_comp is to update the list of pointers for labels inserted into the message as the name is compressed. If dnptr is NULL, names are not compressed. If lastdnptr is NULL, the list of labels is not updated. The dn_expand entry expands the compressed domain name comp_dn to a full domain name. The compressed name is contained in a query or reply message; msg is a pointer to the beginning of the message. The uncompressed name is placed in the buffer indicated by exp_dn which is of size length . The size of compressed name is returned or -1 if there was an error. FILES /etc/resolv.conf see resolver(5) SEE ALSO gethostbyname(3), named(8), resolver(5), hostname(7), RFC1032, RFC1033, RFC1034, RFC1035, RFC974, SMM:11 Name Server Operations Guide for BIND OTHER INFO These functions are part of the Tnet library.