BSD 4_4 release
[unix-history] / usr / src / share / man / man3 / intro.3
index 68919fb..ea77402 100644 (file)
-.\" Copyright (c) 1980 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1980, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.
 .\"
 .\"
-.\"    @(#)intro.3     6.9 (Berkeley) 6/23/90
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
 .\"
 .\"
-.TH INTRO 3 "June 23, 1990"
-.UC 4
-.SH NAME
-intro \- introduction to C library functions
-.SH DESCRIPTION
-This section describes functions that may be found
-in various libraries.
-The library functions are those other than the
-functions which directly invoke UNIX system primitives, described in section 2.
-Most of these functions are accessible from the C library,
-.IR libc ,
-which is automatically loaded by the C compiler
-.IR cc (1),
-and the Pascal compiler
-.IR pc (1).
-The link editor
-.IR ld (1)
-searches this library under the `\-lc' option.
-The C library also includes all the functions described in section 2.
-.PP
-A subset of these functions are available from Fortran;
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)intro.3    8.1 (Berkeley) 6/5/93
+.\"
+.Dd June 5, 1993
+.Dt INTRO 3
+.Os BSD 4
+.Sh NAME
+.Nm intro
+.Nd introduction to the C libraries
+.Sh DESCRIPTION
+This section provides an overview of the C
+library functions, their error returns and other
+common definitions and concepts.
+Most of these functions are available from the C library,
+.Em libc
+(see
+.Xr libc 3 ) .
+Other libraries, such as the math library,
+.Em libm ,
+must be indicated at compile time with the
+.Fl l
+option of the compiler.
+.Pp
+A subset of the
+.Xr libc functions
+are available from Fortran;
 they are described separately in
 they are described separately in
-.IR intro (3F).
-.PP
-The functions described in this section are grouped into various sections:
-.TP
-(3)
-The straight ``3'' functions are the standard C library functions.
-.TP
-(3N)
-These functions constitute the internet network library.
-.TP 
-(3S)
-These functions constitute the `standard I/O package', see
-.IR stdio (3S)
-for more details.
-Declarations for these functions may be obtained from
-the include file
-.RI < stdio.h >.
-.TP
-(3C)
-These routines are included for compatibility with other systems.
+.Xr intro 3f .
+.Pp
+The various libraries (followed by the loader flag):
+.Bl -tag -width "libc (-lc)"
+.It Xr libc Pq Fl l Ns Ar c
+Standard C library functions. (See
+.Xr libc 3 . ) When using the C compiler
+.Xr cc 1 ,
+it is not necessary
+to supply the loader flag
+.Fl l Ns Ar c
+for these functions.
+There are several `libraries' or groups of functions included inside of
+.Xr libc : the standard
+.Tn I/O
+routines,
+database routines,
+bit operators,
+string operators,
+character tests and character operators,
+des encryption routines,
+storage allocation, time functions, signal handling and more.
+.It Xo
+.Xr libcurses
+.Pf ( Fl l Ns Ar curses
+.Fl l Ns Ar termcap )
+.Xc
+Terminal independent screen management routines
+for two dimensional non-bitmap display terminals.
+(See
+.Xr curses 3 . )
+.It Xr libcompat Pq Fl l Ns Ar compat
+Functions which are obsolete but are available for compatibility with
+.Bx 4.3 .
 In particular,
 a number of system call interfaces provided in previous releases of
 In particular,
 a number of system call interfaces provided in previous releases of
-4BSD have been included for source code compatibility.
+.Bx
+have been included for source code compatibility.
 Use of these routines should, for the most part, be avoided.
 The manual page entry for each compatibility routine
 indicates the proper interface to use. 
 Use of these routines should, for the most part, be avoided.
 The manual page entry for each compatibility routine
 indicates the proper interface to use. 
-.TP
-(3M)
-These functions constitute the math library,
-.IR libm .
-When functions in the math library (see
-.IR math (3M))
-are passed values that are undefined or would generate
-answers that are out of range,
-they call the \fIinfnan\fP routine.
-By default this routine returns the VAX reserved floating point value
-which causes the process to get a floating point exception (see
-.IR sigvec (2)).
-Programs that wish to take other action should define their own
-version of \fIinfnan\fP (see
-.IR infnan (3M)
-for details).
+.\" .It Xr libkvm
+.It Xr libl Pq Fl l Ns Ar l
+The library for
+.Xr lex 1 .
+.\" .It Xr libln
+.It Xr libm Pq Fl l Ns Ar m
+The math library,
+.Em libm .
 The math library is loaded as needed by the Pascal compiler
 The math library is loaded as needed by the Pascal compiler
-.IR pc (1).
-C programs that wish to use this library need to specify the ``\-lm'' option.
-.TP
-(3X)
-These functions constitute minor libraries and other miscellaneous
-run-time facilities.  Most are available only when programming in C.
-These functions include libraries that provide
-device independent plotting functions,
-terminal independent screen management routines
-for two dimensional non-bitmap display terminals, 
-and functions for managing data bases with inverted indexes.
-These functions are located in separate libraries
-indicated in each manual entry.
-.SH FILES
-.nf
-/usr/lib/libc.a                the C library
-/usr/lib/libm.a                the math library
-/usr/lib/libc_p.a              the C library compiled for profiling
-/usr/lib/libm_p.a              the math library compiled for profiling
-.fi
-.SH SEE ALSO
-stdio(3S),
-math(3M),
-intro(2),
-cc(1),
-ld(1),
-nm(1)
-.SH "LIST OF FUNCTIONS"
-.sp 2
-.nf
-.ta \w'getprotobynumber'u+2n +\w'gethostbyname.3n'u+10n
-\fIName\fP     \fIAppears on Page\fP   \fIDescription\fP
-.ta \w'getprotobynumber'u+4n +\w'gethostbyname.3n'u+4n
-.sp 5p
-abort  abort.3 generate a fault
-abs    abs.3   integer absolute value
-acos   sin.3m  inverse trigonometric function
-acosh  asinh.3m        inverse hyperbolic function
-alarm  alarm.3c        schedule signal after specified time
-alloca malloc.3        memory allocator
-arc    plot.3x graphics interface
-asctime        ctime.3 convert date and time to ASCII
-asin   sin.3m  inverse trigonometric function
-asinh  asinh.3m        inverse hyperbolic function
-assert assert.3x       program verification
-atan   sin.3m  inverse trigonometric function
-atanh  asinh.3m        inverse hyperbolic function
-atan2  sin.3m  inverse trigonometric function
-atof   atof.3  convert ASCII to numbers
-atoi   atof.3  convert ASCII to numbers
-atol   atof.3  convert ASCII to numbers
-bcmp   bstring.3       bit and byte string operations
-bcopy  bstring.3       bit and byte string operations
-bzero  bstring.3       bit and byte string operations
-cabs   hypot.3m        complex absolute value
-calloc malloc.3        memory allocator
-cbrt   sqrt.3m cube root
-ceil   floor.3m        integer no less than
-circle plot.3x graphics interface
-clearerr       ferror.3s       stream status inquiries
-closedir       directory.3     directory operations
-closelog       syslog.3        control system log
-closepl        plot.3x graphics interface
-cont   plot.3x graphics interface
-copysign       ieee.3m copy sign bit
-cos    sin.3m  trigonometric function
-cosh   sinh.3m hyperbolic function
-crypt  crypt.3 DES encryption
-ctime  ctime.3 convert date and time to ASCII
-curses curses.3x       screen functions with ``optimal'' cursor motion
-dbminit        dbm.3x  data base subroutines
-delete dbm.3x  data base subroutines
-drem   ieee.3m remainder
-ecvt   ecvt.3  output conversion
-edata  end.3   last locations in program
-encrypt        crypt.3 DES encryption
-end    end.3   last locations in program
-endfsent       getfsent.3x     get file system descriptor file entry
-endgrent       getgrent.3      get group file entry
-endhostent     gethostbyname.3n        get network host entry
-endnetent      getnetent.3n    get network entry
-endprotoent    getprotoent.3n  get protocol entry
-endpwent       getpwent.3      get password file entry
-endservent     getservent.3n   get service entry
-environ        execl.3 execute a file
-erase  plot.3x graphics interface
-erf    erf.3m  error function
-erfc   erf.3m  complementary error function
-etext  end.3   last locations in program
-exec   execl.3 execute a file
-exece  execl.3 execute a file
-execl  execl.3 execute a file
-execle execl.3 execute a file
-execlp execl.3 execute a file
-exect  execl.3 execute a file
-execv  execl.3 execute a file
-execvp execl.3 execute a file
-exit   exit.3  terminate a process after flushing any pending output
-exp    exp.3m  exponential
-expm1  exp.3m  exp(x)\-1
-fabs   floor.3m        absolute value
-fclose fclose.3s       close or flush a stream
-fcvt   ecvt.3  output conversion
-feof   ferror.3s       stream status inquiries
-ferror ferror.3s       stream status inquiries
-fetch  dbm.3x  data base subroutines
-fflush fclose.3s       close or flush a stream
-ffs    bstring.3       bit and byte string operations
-fgetc  getc.3s get character or word from stream
-fgets  gets.3s get a string from a stream
-fileno ferror.3s       stream status inquiries
-firstkey       dbm.3x  data base subroutines
-floor  floor.3m        integer no greater than
-fopen  fopen.3s        open a stream
-fprintf        printf.3s       formatted output conversion
-fputc  putc.3s put character or word on a stream
-fputs  puts.3s put a string on a stream
-fread  fread.3s        buffered binary input/output
-free   malloc.3        memory allocator
-frexp  frexp.3 split into mantissa and exponent
-fscanf scanf.3s        formatted input conversion
-fseek  fseek.3s        reposition a stream
-ftell  fseek.3s        reposition a stream
-ftime  time.3c get date and time
-fwrite fread.3s        buffered binary input/output
-gcvt   ecvt.3  output conversion
-getc   getc.3s get character or word from stream
-getchar        getc.3s get character or word from stream
-getdiskbyname  getdisk.3x      get disk description by its name
-getenv getenv.3        value for environment name
-getfsent       getfsent.3x     get file system descriptor file entry
-getfsfile      getfsent.3x     get file system descriptor file entry
-getfsspec      getfsent.3x     get file system descriptor file entry
-getfstype      getfsent.3x     get file system descriptor file entry
-getgrent       getgrent.3      get group file entry
-getgrgid       getgrent.3      get group file entry
-getgrnam       getgrent.3      get group file entry
-gethostbyaddr  gethostbyname.3n        get network host entry
-gethostbyname  gethostbyname.3n        get network host entry
-gethostent     gethostbyname.3n        get network host entry
-getlogin       getlogin.3      get login name
-getnetbyaddr   getnetent.3n    get network entry
-getnetbyname   getnetent.3n    get network entry
-getnetent      getnetent.3n    get network entry
-getpass        getpass.3       read a password
-getprotobyname getprotoent.3n  get protocol entry
-getprotobynumber       getprotoent.3n  get protocol entry
-getprotoent    getprotoent.3n  get protocol entry
-getpw  getpw.3 get name from uid
-getpwent       getpwent.3      get password file entry
-getpwnam       getpwent.3      get password file entry
-getpwuid       getpwent.3      get password file entry
-gets   gets.3s get a string from a stream
-getservbyname  getservent.3n   get service entry
-getservbyport  getservent.3n   get service entry
-getservent     getservent.3n   get service entry
-getw   getc.3s get character or word from stream
-getwd  getwd.3 get current working directory pathname
-gmtime ctime.3 convert date and time to ASCII
-gtty   stty.3c set and get terminal state (defunct)
-htonl  byteorder.3n    convert values between host and network byte order
-htons  byteorder.3n    convert values between host and network byte order
-hypot  hypot.3m        Euclidean distance
-index  string.3        string operations
-inet_addr      inet.3n Internet address manipulation routines
-inet_lnaof     inet.3n Internet address manipulation routines
-inet_makeaddr  inet.3n Internet address manipulation routines
-inet_netof     inet.3n Internet address manipulation routines
-inet_network   inet.3n Internet address manipulation routines
-infnan infnan.3m       signals exceptions
-initgroups     initgroups.3x   initialize group access list
-initstate      random.3        better random number generator
-insque insque.3        insert/remove element from a queue
-isalnum        ctype.3 character classification macros
-isalpha        ctype.3 character classification macros
-isascii        ctype.3 character classification macros
-isatty ttyname.3       find name of a terminal
-iscntrl        ctype.3 character classification macros
-isdigit        ctype.3 character classification macros
-islower        ctype.3 character classification macros
-isprint        ctype.3 character classification macros
-ispunct        ctype.3 character classification macros
-isspace        ctype.3 character classification macros
-isupper        ctype.3 character classification macros
-j0     j0.3m   bessel function
-j1     j0.3m   bessel function
-jn     j0.3m   bessel function
-label  plot.3x graphics interface
-ldexp  frexp.3 split into mantissa and exponent
-lgamma lgamma.3m       log gamma function; (formerly gamma.3m)
-lib2648        lib2648.3x      subroutines for the HP 2648 graphics terminal
-line   plot.3x graphics interface
-linemod        plot.3x graphics interface
-localtime      ctime.3 convert date and time to ASCII
-log    exp.3m  natural logarithm
-logb   ieee.3m exponent extraction
-log10  exp.3m  logarithm to base 10
-log1p  exp.3m  log(1+x)
-longjmp        setjmp.3        non-local goto
-malloc malloc.3        memory allocator
-mktemp mktemp.3        make a unique file name
-modf   frexp.3 split into mantissa and exponent
-moncontrol     monitor.3       prepare execution profile
-monitor        monitor.3       prepare execution profile
-monstartup     monitor.3       prepare execution profile
-move   plot.3x graphics interface
-nextkey        dbm.3x  data base subroutines
-nice   nice.3c set program priority
-nlist  nlist.3 get entries from name list
-ntohl  byteorder.3n    convert values between host and network byte order
-ntohs  byteorder.3n    convert values between host and network byte order
-opendir        directory.3     directory operations
-openlog        syslog.3        control system log
-openpl plot.3x graphics interface
-pause  pause.3c        stop until signal
-pclose popen.3 initiate I/O to/from a process
-perror perror.3        system error messages
-point  plot.3x graphics interface
-popen  popen.3 initiate I/O to/from a process
-pow    exp.3m  exponential x**y
-printf printf.3s       formatted output conversion
-psignal        psignal.3       system signal messages
-putc   putc.3s put character or word on a stream
-putchar        putc.3s put character or word on a stream
-puts   puts.3s put a string on a stream
-putw   putc.3s put character or word on a stream
-qsort  qsort.3 quicker sort
-rand   rand.3c random number generator
-random random.3        better random number generator
-rcmd   rcmd.3x routines for returning a stream to a remote command
-re_comp        regex.3 regular expression handler
-re_exec        regex.3 regular expression handler
-readdir        directory.3     directory operations
-realloc        malloc.3        memory allocator
-remque insque.3        insert/remove element from a queue
-rewind fseek.3s        reposition a stream
-rewinddir      directory.3     directory operations
-rexec  rexec.3x        return stream to a remote command
-rindex string.3        string operations
-rint   floor.3m        round to nearest integer
-rresvport      rcmd.3x routines for returning a stream to a remote command
-ruserok        rcmd.3x routines for returning a stream to a remote command
-scalb  ieee.3m exponent adjustment
-scandir        scandir.3       scan a directory
-scanf  scanf.3s        formatted input conversion
-seekdir        directory.3     directory operations
-setbuf setbuf.3s       assign buffering to a stream
-setbuffer      setbuf.3s       assign buffering to a stream
-setegid        setuid.3        set user and group ID
-seteuid        setuid.3        set user and group ID
-setfsent       getfsent.3x     get file system descriptor file entry
-setgid setuid.3        set user and group ID
-setgrent       getgrent.3      get group file entry
-sethostent     gethostbyname.3n        get network host entry
-setjmp setjmp.3        non-local goto
-setkey crypt.3 DES encryption
-setlinebuf     setbuf.3s       assign buffering to a stream
-setnetent      getnetent.3n    get network entry
-setprotoent    getprotoent.3n  get protocol entry
-setpwent       getpwent.3      get password file entry
-setrgid        setuid.3        set user and group ID
-setruid        setuid.3        set user and group ID
-setservent     getservent.3n   get service entry
-setstate       random.3        better random number generator
-setuid setuid.3        set user and group ID
-signal signal.3        simplified software signal facilities
-sin    sin.3m  trigonometric function
-sinh   sinh.3m hyperbolic function
-sleep  sleep.3 suspend execution for interval
-space  plot.3x graphics interface
-sprintf        printf.3s       formatted output conversion
-sqrt   sqrt.3m square root
-srand  rand.3c random number generator
-srandom        random.3        better random number generator
-sscanf scanf.3s        formatted input conversion
-stdio  intro.3s        standard buffered input/output package
-store  dbm.3x  data base subroutines
-strcat string.3        string operations
-strcmp string.3        string operations
-strcpy string.3        string operations
-strlen string.3        string operations
-strncat        string.3        string operations
-strncmp        string.3        string operations
-strncpy        string.3        string operations
-stty   stty.3c set and get terminal state (defunct)
-swab   swab.3  swap bytes
-sys_errlist    perror.3        system error messages
-sys_nerr       perror.3        system error messages
-sys_siglist    psignal.3       system signal messages
-syslog syslog.3        control system log
-system system.3        issue a shell command
-tan    sin.3m  trigonometric function
-tanh   sinh.3m hyperbolic function
-telldir        directory.3     directory operations
-tgetent        termcap.3x      terminal independent operation routines
-tgetflag       termcap.3x      terminal independent operation routines
-tgetnum        termcap.3x      terminal independent operation routines
-tgetstr        termcap.3x      terminal independent operation routines
-tgoto  termcap.3x      terminal independent operation routines
-time   time.3c get date and time
-times  times.3c        get process times
-timezone       ctime.3 convert date and time to ASCII
-tputs  termcap.3x      terminal independent operation routines
-ttyname        ttyname.3       find name of a terminal
-ttyslot        ttyname.3       find name of a terminal
-ungetc ungetc.3s       push character back into input stream
-utime  utime.3c        set file times
-valloc valloc.3        aligned memory allocator
-varargs        varargs.3       variable argument list
-vlimit vlimit.3c       control maximum system resource consumption
-vtimes vtimes.3c       get information about resource utilization
-y0     j0.3m   bessel function
-y1     j0.3m   bessel function
-yn     j0.3m   bessel function
-.fi
+.Xr pc 1 ,
+but not by the C compiler which requires the
+.Fl l Ns Ar m
+flag.
+(See
+.Xr math 3 . )
+.It Xr libmp Pq Fl l Ns Ar mp
+.\" .It Xr libom
+.\" Old math library.
+.It Xr libplot Pq Fl l Ns Ar plot
+Device independent plotting functions. 
+(See
+.Xr plot 3 . )
+.It Xr libplotf77 Pq Fl l Ns Ar plotf77
+The device independent plotting functions for fortran. 
+(See
+.Xr plot 3 . )
+.\" .It Xr libresolv Pq Fl l Ns Ar resolv
+.\" Routines for network address resolution.
+.It Xr libtermcap Fl l Ns Ar termcap
+The terminal independent operation library package. (See
+.Xr termcap 3 . )
+.\" .It libvt0.a
+.It Xr liby Pq Fl l Ns Ar y
+The library for
+.Xr yacc 1 .
+.El
+.Sh FILES
+.Bl -tag -width /usr/lib/libm_p.a -compact
+.It Pa /usr/lib/libc.a
+the C library
+.It Pa /usr/lib/libm.a
+the math library
+.It Pa /usr/lib/libc_p.a
+the C library compiled for profiling
+.It Pa /usr/lib/libm_p.a
+the math library compiled for profiling
+.El
+.Sh SEE ALSO
+.\" .Xr libc 3 ,
+.Xr stdio 3 ,
+.Xr math 3 ,
+.Xr intro 2 ,
+.Xr cc 1 ,
+.Xr ld 1 ,
+.Xr nm 1
+.\" .Sh LIST OF FUNCTIONS
+.\" .Bl -column "strncasecmpxxx" "system"
+.\" .Sy Name   Description
+.\" .El
+.Sh HISTORY
+An
+.Nm intro
+manual appeared in
+.At v7 .