Unix/Linux Go Back    

Plan 9 - man page for 0intro (plan9 section 2)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

INTRO(2)										 INTRO(2)

       intro - introduction to library functions

       #include <u.h>

       #include <libc.h>

       #include <auth.h>

       #include <bio.h>

       #include <fcall.h>

       #include <frame.h>

       #include <layer.h>

       #include <libg.h>

       #include <mach.h>

       #include <ndb.h>

       #include <panel.h>

       #include <regexp.h>

       #include <stdio.h>

       This section describes functions in various libraries.  For the most part, each library is
       defined by a single C include file, listed above, and a single archive file containing the
       library	proper.   The name of the archive is /$objtype/lib/libx.a, where x is the base of
       the include file name, stripped of a  leading  lib  if  present.   For  example,  <libg.h>
       defines	the contents of library /$objtype/lib/libg.a, which may be abbreviated when named
       to the loader as -lg.  In practice, each include file contains a #pragma that directs  the
       loader  to pick up the associated archive automatically, so it is rarely necessary to tell
       the loader which libraries a program needs.

       The library to which a function belongs is defined by the header  file  that  defines  its
       interface.   The `C library', libc, contains most of the basic subroutines such as strlen.
       Declarations for all of these functions are in <libc.h>, which must be preceded by (needs)
       an  include  of	<u.h>.	 The graphics library, libg, the graphics library.  is defined by
       <libg.h>, which needs <libc.h> and <u.h>.  The Buffered I/O library, libbio, is defined by
       <bio.h>,  which	needs  <libc.h> and <u.h>.  The ANSI C Standard I/O library, libstdio, is
       defined by <stdio.h>, which has no prerequisites.  There are a few  other,  less  commonly
       used libraries defined on individual pages of this section.

       The include file <u.h>, a prerequisite of several other include files, declares the archi-
       tecture-dependent and  -independent  types,  including:	ushort,  uchar,  and  ulong,  the
       unsigned  integer  types;  schar,  the signed char type; vlong, a very long integral type;
       jmp_buf, the type of the argument to setjmp and longjmp, plus macros that define the  lay-
       out of jmp_buf (see setjmp(2)); definitions of the bits in the floating-point control reg-
       ister as used by getfcr(2); and Length, a union	giving	different  views  of  the  64-bit
       length of a file, declared something like

	      typedef union
		    char   clength[8];
		    vlong  vlength;
			   long hlength;   /* high order */
			   long length;    /* low order */
	      } Length;

   Name space
       Files  are  collected  into  a  hierarchical organization called a file tree starting in a
       directory called the root.  File names, also called paths, consist of a number of  /-sepa-
       rated  path  elements  with the slashes corresponding to directories.  A path element must
       contain only printable characters (those outside ASCII and  Latin-1  control  space)  that
       occupy no more than NAMELEN-1 bytes.  A path element cannot contain a space or slash.

       When a process presents a file name to Plan 9, it is evaluated by the following algorithm.
       Start with a directory that depends on the first character of the path: means the root  of
       the  main  hierarchy,  means the separate root of a kernel device's file tree (see Section
       3), and anything else means the process's current working directory.  Then for  each  path
       element,  look  up  the element in the directory, advance to that directory, do a possible
       translation (see below), and repeat.  The last step may yield a directory or regular file.
       The collection of files reachable from the root is called the name space of a process.

       A  program  can	use  bind or mount (see bind(2)) to say that whenever a specified file is
       reached during evaluation, evaluation instead continues	from  a  second  specified  file.
       Also, the same system calls create union directories, which are concatenations of ordinary
       directories that are searched sequentially until the desired element is found.  Using bind
       and  mount to do name space adjustment affects only the current process group (see below).
       Certain conventions about the layout of the name space should  be  preserved;  see  names-

   File I/O
       Files  are opened for input or output by open or create (see open(2)).  These calls return
       an integer called a file descriptor which identifies the file  to  subsequent  I/O  calls,
       notably	read(2)  and  write.   File descriptors range from 0 to 99 in the current system.
       The system allocates the numbers by selecting the lowest unused descriptor.  They  may  be
       reassigned  using  dup(2).   File  descriptors  are  indices  into  a kernel resident file
       descriptor table.  Each process has an associated file descriptor table.   In  some  cases
       (see rfork in fork(2)) a file descriptor table may be shared by several processes.

       By convention, file descriptor 0 is the standard input, 1 is the standard output, and 2 is
       the standard error output.  With one exception, the operating system is unaware	of  these
       conventions;  it is permissible to close file 0, or even to replace it by a file open only
       for writing, but many programs will be confused by such chicanery.  The exception is  that
       the system prints messages about broken processes to file descriptor 2.

       Files  are  normally read or written in sequential order.  The I/O position in the file is
       called the file offset and may be set arbitrarily using the seek(2) system call.

       Directories may be opened and read much like regular files.  They contain an integral num-
       ber  of	records,  called directory entries, of length DIRLEN (defined in <libc.h>).  Each
       entry is a machine-independent representation of the information about an existing file in
       the  directory,	including  the name, ownership, permission, access dates, and so on.  The
       entry corresponding to an arbitrary file can be retrieved by stat(2) or fstat;  wstat  and
       fwstat write back entries, thus changing the properties of a file.  An entry may be trans-
       lated into a more convenient, addressable form called a Dir structure; dirstat,	dirfstat,
       dirwstat, and dirfwstat execute the appropriate translations (see stat(2)).

       New  files  are made with create (in open(2)) and deleted with remove(2).  Directories may
       not directly be written; create, remove, wstat, and fwstat alter them.

       Pipe(2) creates a connected pair of file descriptors, useful for bidirectional local  com-

   Process execution and control
       A new process is created when an existing one calls rfork with the RFPROC bit set, usually
       just by calling fork(2).  The new (child) process starts out with copies  of  the  address
       space  and  most  other	attributes of the old (parent) process.  In particular, the child
       starts out running the same program as the parent; exec(2) will bring in a different one.

       Each process has a unique integer process id;  a  set  of  open	files,	indexed  by  file
       descriptor; and a current working directory (changed by chdir(2)).

       Each  process  has a set of attributes -- memory, open files, name space, etc. -- that may
       be shared or unique.  Flags to rfork control the sharing of these attributes.

       The memory of a process is divided into segments.  Every  program  has  at  least  a  text
       (instruction) and stack segment.  Most also have an initialized data segment and a segment
       of zero-filled data called bss.	Processes may segattach(2)  other  segments  for  special

       A process terminates by calling exits(2).  A parent process may call wait (in exits(2)) to
       wait for some child to terminate.  A string of status information may be passed from exits
       to wait.  A process can go to sleep for a specified time by calling sleep(2).

       There  is  a  notification  mechanism  for  telling a process about events such as address
       faults, floating point  faults,	and  messages  from  other  processes.	 A  process  uses
       notify(2)  to  register	the  function  to  be called (the notification handler) when such
       events occur.

       Most of the functions in this section are available in the same form from Alef, with  byte
       substituted  for char and uchar and int for long, and with adjustment for Alef having only
       one floating-point type, called float, holding double-precision values.	The  main  excep-
       tions  are that the long-valued functions such as strtoul have their final l changed to an
       i to reflect the different type structure of the language; that the Bio library has a dif-
       ferent  organization  (see  Bio(2)  for	details); and for various reasons some things are
       missing, notably ctype and the Stdio, IP, Layer, Lock, Mach,  Ndb,  and	Panel  libraries.
       Also,  there  is  no  <u.h>; instead <alef.h> replaces both it and <libc.h>.  The machine-
       dependent definitions in Alef, which are only needed for getfcr(2) and relatives,  are  in

       Within  this  manual,  only explicit differences in the Alef libraries are documented, the
       Alef functions are not all indexed, and the substitutions for <libc.h> as  well	as  char,
       uchar,	etc.	are   assumed.	 The  sources  to  the	Alef  libraries  all  live  under

       NOTE: Because the languages have different calling conventions, Alef  programs  cannot  be
       linked with C libraries.

       nm(1), 2l(1), 2c(1)

       Math  functions in libc return special values when the function is undefined for the given
       arguments or when the value is not representable (see nan(2)).

       Some of the functions in libc are system calls and many	others	employ	system	calls  in
       their  implementation.  All system calls return integers, with -1 indicating that an error
       occurred; errstr(2) recovers a string describing the error.  Some user-level library func-
       tions also use the errstr mechanism to report errors.  Functions that may affect the value
       of the error string are said to ``set errstr''; it is understood that the error string  is
       altered only if an error occurs.

Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 03:52 PM.