glenda.party
term% ls -F
term% cat index.txt
INTRO(2)                      System Calls Manual                     INTRO(2)



NAME
       intro - introduction to library functions

SYNOPSIS
       #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>

DESCRIPTION
       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.  Us‐
       ing 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 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 en‐
       try is a machine-independent representation of the information about an
       existing file in the directory, including the name, ownership,  permis‐
       sion, 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
       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  re‐
       move(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 RF‐
       PROC 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  run‐
       ning  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,  in‐
       dexed  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 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.

   Multithreading
       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; de‐
       tails 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 re‐
       sult to the main processes over a channel when the  request  completes.
       For examples of this design, see ioproc(2) or mouse(2).

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

DIAGNOSTICS
       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.



                                                                      INTRO(2)