intro man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

INTRO(2)							      INTRO(2)

       intro - introduction to library functions

       #include <u.h>

       #include <libc.h>

       #include <auth.h>

       #include <bio.h>

       #include <draw.h>

       #include <fcall.h>

       #include <frame.h>

       #include <mach.h>

       #include <ndb.h>

       #include <regexp.h>

       #include <stdio.h>

       #include <thread.h>

       This  section  describes	 functions in various libraries.  For the most
       part, each library is defined by a single C include file, such as those
       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 exam‐
       ple, <draw.h> defines the contents of library  /$objtype/lib/libdraw.a,
       which  may be abbreviated when named to the loader as -ldraw.  In prac‐
       tice, 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, draw, is defined  by  <draw.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 needs <u.h>.	 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 architecture-dependent and -independent types,  including:
       uchar,  ushort, uint, and ulong, the unsigned integer types; schar, the
       signed char type; vlong and uvlong, the signed and unsigned  very  long
       integral	 types;	 Rune,	the  Unicode  character	 type;	u8int, u16int,
       u32int, and u64int, the unsigned integral types with  specific  widths;
       uintptr,	 the  unsigned integral type with the same width as a pointer;
       jmp_buf, the type of the argument to setjmp and	longjmp,  plus	macros
       that  define  the layout of jmp_buf (see setjmp(2)); definitions of the
       bits in the floating-point control register as used by  getfcr(2);  and
       the macros va_arg and friends for accessing arguments of variadic func‐
       tions (identical to the macros defined in <stdarg.h> in ANSI C).

   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	/-separated  path  elements  with  the
       slashes corresponding to directories.  A path element must contain only
       printable characters (those outside the control	spaces	of  ASCII  and
       Latin-1).  A path element cannot contain a 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  any‐
       thing  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 contin‐
       ues  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  cur‐
       rent  process  group (see below).  Certain conventions about the layout
       of the name space should be preserved; see namespace(4).

   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.  The  sys‐
       tem  allocates  the  numbers by selecting the lowest unused descriptor.
       They are allocated dynamically; there is no visible limit to the number
       of  file	 descriptors  a process may have open.	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 ta‐
       ble.  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 stan‐
       dard 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 descrip‐
       tor 2.

       Files  are normally read or written in sequential order.	 The I/O posi‐
       tion 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 con‐
       tain an integral number of records,  called  directory  entries.	  Each
       entry  is a machine-independent representation of the information about
       an existing file in the directory, including the name, ownership,  per‐
       mission,	 access dates, and so on.  The entry corresponding to an arbi‐
       trary 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
       translated into a more convenient, addressable form called a Dir struc‐
       ture;  dirstat, dirfstat, dirwstat, and dirfwstat execute the appropri‐
       ate translations (see stat(2)).

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

       The operating system kernel records the file name used to  access  each
       open  file  or  directory.   If the file is opened by a local name (one
       that does not begin / or #), the system makes the stored name  absolute
       by prefixing the string associated with the current directory.  Similar
       lexical adjustments are made for path names containing .	 (dot)	or  ..
       (dot-dot).  By this process, the system maintains a record of the route
       by which each file was accessed.	 Although there is a  possibility  for
       error—the  name is not maintained after the file is opened, so removals
       and renamings can confound it—this simple method	 usually  permits  the
       system to return, via the fd2path(2) system call and related calls such
       as getwd(2), a valid name that may be used to find a file again.	  This
       is  also	 the source of the names reported in the name space listing of
       ns(1) or /dev/ns (see proc(3)).

       Pipe(2) creates a connected pair of file descriptors, useful for	 bidi‐
       rectional local communication.

   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

       Each process has a set of attributes — memory, open files, name	space,
       etc.  — that may be shared or unique.  Flags to rfork control the shar‐
       ing 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 ini‐
       tialized data segment and a segment of  zero-filled  data  called  bss.
       Processes may segattach(2) other segments for special purposes.

       A  process  terminates  by calling exits(2).  A parent process may call
       wait(2) to wait for some child to terminate.  A string of status infor‐
       mation 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.

       By  calling  rfork with the RFMEM bit set, a program may create several
       independently executing processes sharing the same memory  (except  for
       the  stack  segment,  which is unique to each process).	Where possible
       according to the ANSI C standard, the main C library works properly  in
       multiprocess  programs; malloc, print, and the other routines use locks
       (see lock(2)) to synchronize access  to	their  data  structures.   The
       graphics	 library  defined  in  <draw.h> is also multi-process capable;
       details are in graphics(2).  In general, though, multiprocess  programs
       should use some form of synchronization to protect shared data.

       The  thread library, defined in <thread.h>, provides support for multi‐
       process programs.  It includes a data structure called a	 Channel  that
       can  be	used  to  send	messages between processes, and coroutine-like
       threads, which enable multiple  threads	of  control  within  a	single
       process.	  The  threads	within a process are scheduled by the library,
       but there is no pre-emptive scheduling within a process; thread switch‐
       ing occurs only at communication or synchronization points.

       Most programs using the thread library comprise multiple processes com‐
       municating over channels, and within some processes, multiple  threads.
       Since  Plan  9  I/O  calls  may	block, a system call may block all the
       threads in a process.  Therefore, a program that shouldn't block	 unex‐
       pectedly	 will  use  a  process	to  serve the I/O request, passing the
       result to the main processes over a channel when the request completes.
       For examples of this design, see ioproc(2) or mouse(2).

       nm(1), 8l(1), 8c(1)

       Math functions in libc return special values when the function is unde‐
       fined 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	 inte‐
       gers,  with  -1 indicating that an error occurred; errstr(2) recovers a
       string describing the error.  Some user-level  library  functions  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	under‐
       stood that the error string is altered only if an error occurs.

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net