1
0

0intro 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457
  1. .TH INTRO 2
  2. .SH NAME
  3. intro \- introduction to library functions
  4. .SH SYNOPSIS
  5. .nf
  6. .B #include <u.h>
  7. .PP
  8. .B #include <libc.h>
  9. .PP
  10. .B #include <auth.h>
  11. .PP
  12. .B #include <bio.h>
  13. .PP
  14. .B #include <draw.h>
  15. .PP
  16. .B #include <fcall.h>
  17. .PP
  18. .B #include <frame.h>
  19. .PP
  20. .B #include <mach.h>
  21. .PP
  22. .B #include <ndb.h>
  23. .PP
  24. .B #include <regexp.h>
  25. .PP
  26. .B #include <stdio.h>
  27. .PP
  28. .B #include <thread.h>
  29. .fi
  30. .SH DESCRIPTION
  31. This section describes functions
  32. in various libraries.
  33. For the most part, each library is defined by a single C include
  34. file, such as those listed above, and a single archive file containing
  35. the library proper. The name of the archive is
  36. .BI /$objtype/lib/lib x .a \f1,
  37. where
  38. .I x
  39. is the base of the include file name, stripped of a leading
  40. .B lib
  41. if present.
  42. For example,
  43. .B <draw.h>
  44. defines the contents of library
  45. .BR /$objtype/lib/libdraw.a ,
  46. which may be abbreviated when named to the loader as
  47. .BR -ldraw .
  48. In practice, each include file contains a
  49. .B #pragma
  50. that directs the loader to pick up the associated archive
  51. automatically, so it is rarely necessary to tell the loader
  52. which
  53. libraries a program needs.
  54. .PP
  55. The library to which a function belongs is defined by the
  56. header file that defines its interface.
  57. The `C library',
  58. .IR libc ,
  59. contains most of the basic subroutines such
  60. as
  61. .IR strlen .
  62. Declarations for all of these functions are
  63. in
  64. .BR <libc.h> ,
  65. which must be preceded by
  66. .RI ( needs )
  67. an include of
  68. .BR <u.h> .
  69. The graphics library,
  70. .IR draw ,
  71. is defined by
  72. .BR <draw.h> ,
  73. which needs
  74. .B <libc.h>
  75. and
  76. .BR <u.h> .
  77. The Buffered I/O library,
  78. .IR libbio ,
  79. is defined by
  80. .BR <bio.h> ,
  81. which needs
  82. .B <libc.h>
  83. and
  84. .BR <u.h> .
  85. The ANSI C Standard I/O library,
  86. .IR libstdio ,
  87. is defined by
  88. .BR <stdio.h> ,
  89. which needs
  90. .BR <u.h> .
  91. There are a few other, less commonly used libraries defined on
  92. individual pages of this section.
  93. .PP
  94. The include file
  95. .BR <u.h> ,
  96. a prerequisite of several other include files,
  97. declares the architecture-dependent and -independent types, including:
  98. .IR uchar ,
  99. .IR ushort ,
  100. .IR uint ,
  101. and
  102. .IR ulong ,
  103. the unsigned integer types;
  104. .IR schar ,
  105. the signed char type;
  106. .I vlong
  107. and
  108. .IR uvlong ,
  109. the signed and unsigned very long integral types;
  110. .IR Rune ,
  111. the Unicode character type;
  112. .IR u8int ,
  113. .IR u16int ,
  114. .IR u32int ,
  115. and
  116. .IR u64int ,
  117. the unsigned integral types with specific widths;
  118. .IR uintptr ,
  119. the unsigned integral type with the same width as a pointer;
  120. .IR jmp_buf ,
  121. the type of the argument to
  122. .I setjmp
  123. and
  124. .IR longjmp ,
  125. plus macros that define the layout of
  126. .IR jmp_buf
  127. (see
  128. .IR setjmp (2));
  129. definitions of the bits in the floating-point control register
  130. as used by
  131. .IR getfcr (2);
  132. and
  133. the macros
  134. .B va_arg
  135. and friends for accessing arguments of variadic functions (identical to the
  136. macros defined in
  137. .B <stdarg.h>
  138. in ANSI C).
  139. .SS "Name space
  140. Files are collected into a hierarchical organization called a
  141. .I "file tree
  142. starting in a
  143. .I directory
  144. called the
  145. .IR root .
  146. File names, also called
  147. .IR paths ,
  148. consist of a number of
  149. .BR / -separated
  150. .I "path elements"
  151. with the slashes corresponding to directories.
  152. A path element must contain only printable
  153. characters (those outside the control spaces of
  154. .SM ASCII
  155. and Latin-1).
  156. A path element cannot contain a slash.
  157. .PP
  158. When a process presents a file name to Plan 9, it is
  159. .I evaluated
  160. by the following algorithm.
  161. Start with a directory that depends on the first
  162. character of the path:
  163. .L /
  164. means the root of the main hierarchy,
  165. .L #
  166. means the separate root of a kernel device's file tree (see Section 3),
  167. and anything else means the process's current working directory.
  168. Then for each path element, look up the element
  169. in the directory, advance to that directory,
  170. do a possible translation (see below), and repeat.
  171. The last step may yield a directory or regular file.
  172. The collection of files reachable from the root is called the
  173. .I "name space
  174. of a process.
  175. .PP
  176. A program can use
  177. .I bind
  178. or
  179. .I mount
  180. (see
  181. .IR bind (2))
  182. to say that whenever a specified file is reached during evaluation,
  183. evaluation instead continues from a second specified file.
  184. Also, the same system calls create
  185. .IR "union directories" ,
  186. which are concatenations of ordinary directories
  187. that are searched sequentially until the desired element is found.
  188. Using
  189. .I bind
  190. and
  191. .I mount
  192. to do name space adjustment affects only
  193. the current process group (see below).
  194. Certain conventions about the layout of the name space should
  195. be preserved; see
  196. .IR namespace (4).
  197. .SS "File I/O"
  198. Files are opened for input or output
  199. by
  200. .I open
  201. or
  202. .I create
  203. (see
  204. .IR open (2)).
  205. These calls return an integer called a
  206. .IR "file descriptor"
  207. which identifies the file
  208. to subsequent I/O calls,
  209. notably
  210. .IR read (2)
  211. and
  212. .IR write .
  213. The system allocates the numbers by selecting the lowest unused descriptor.
  214. They are allocated dynamically; there is no visible limit to the number of file
  215. descriptors a process may have open.
  216. They may be reassigned using
  217. .IR dup (2).
  218. File descriptors are indices into a
  219. kernel resident
  220. .IR "file descriptor table" .
  221. Each process has an associated file descriptor table.
  222. In some cases (see
  223. .I rfork
  224. in
  225. .IR fork (2))
  226. a file descriptor table may be shared by several processes.
  227. .PP
  228. By convention,
  229. file descriptor 0 is the standard input,
  230. 1 is the standard output,
  231. and 2 is the standard error output.
  232. With one exception, the operating system is unaware of these conventions;
  233. it is permissible to close file 0,
  234. or even to replace it by a file open only for writing,
  235. but many programs will be confused by such chicanery.
  236. The exception is that the system prints messages about broken processes
  237. to file descriptor 2.
  238. .PP
  239. Files are normally read or written in sequential order.
  240. The I/O position in the file is called the
  241. .IR "file offset"
  242. and may be set arbitrarily using the
  243. .IR seek (2)
  244. system call.
  245. .PP
  246. Directories may be opened and read much like regular files.
  247. They contain an integral number of records, called
  248. .IR "directory entries" .
  249. Each entry is a machine-independent representation of
  250. the information about an existing file in the directory,
  251. including the name, ownership,
  252. permission,
  253. access dates,
  254. and so on.
  255. The entry
  256. corresponding to an arbitrary file can be retrieved by
  257. .IR stat (2)
  258. or
  259. .IR fstat ;
  260. .I wstat
  261. and
  262. .I fwstat
  263. write back entries, thus changing the properties of a file.
  264. An entry may be translated into a more convenient, addressable
  265. form called a
  266. .B Dir
  267. structure;
  268. .IR dirstat ,
  269. .IR dirfstat,
  270. .IR dirwstat ,
  271. and
  272. .I dirfwstat
  273. execute the appropriate translations (see
  274. .IR stat (2)).
  275. .PP
  276. New files are made with
  277. .I create
  278. (see
  279. .IR open (2))
  280. and deleted with
  281. .IR remove (2).
  282. Directories may not directly be written;
  283. .IR create ,
  284. .IR remove ,
  285. .IR wstat ,
  286. and
  287. .I fwstat
  288. alter them.
  289. .PP
  290. The operating system kernel records the file name used to access each open file or directory.
  291. If the file is opened by a local name (one that does not begin
  292. .B /
  293. or
  294. .BR # ),
  295. the system makes the stored name absolute by prefixing
  296. the string associated with the current directory.
  297. Similar lexical adjustments are made for path names containing
  298. .B .
  299. (dot) or
  300. .B ..
  301. (dot-dot).
  302. By this process, the system maintains a record of the route by which each file was accessed.
  303. Although there is a possibility for error\(emthe name is not maintained after the file is opened,
  304. so removals and renamings can confound it\(emthis simple method usually
  305. permits the system to return, via the
  306. .IR fd2path (2)
  307. system call and related calls such as
  308. .IR getwd (2),
  309. a valid name that may be used to find a file again.
  310. This is also the source of the names reported in the name space listing of
  311. .IR ns (1)
  312. or
  313. .B /dev/ns
  314. (see
  315. .IR proc (3)).
  316. .PP
  317. .IR Pipe (2)
  318. creates a connected pair of file descriptors,
  319. useful for bidirectional local communication.
  320. .SS "Process execution and control"
  321. A new process is created
  322. when an existing one calls
  323. .I rfork
  324. with the
  325. .B RFPROC
  326. bit set, usually just by calling
  327. .IR fork (2).
  328. The new (child) process starts out with
  329. copies of the address space and most other attributes
  330. of the old (parent) process.
  331. In particular,
  332. the child starts out running
  333. the same program as the parent;
  334. .IR exec (2)
  335. will bring in a different one.
  336. .PP
  337. Each process has a unique integer process id;
  338. a set of open files, indexed by file descriptor;
  339. and a current working directory
  340. (changed by
  341. .IR chdir (2)).
  342. .PP
  343. Each process has a set of attributes \(em memory, open files,
  344. name space, etc. \(em that may be shared or unique.
  345. Flags to
  346. .IR rfork
  347. control the sharing of these attributes.
  348. .PP
  349. The memory of a process is divided into
  350. .IR segments .
  351. Every program has at least a
  352. .I text
  353. (instruction) and
  354. .I stack
  355. segment.
  356. Most also have an initialized
  357. .I data
  358. segment and a segment of zero-filled data called
  359. .IR bss .
  360. Processes may
  361. .IR segattach (2)
  362. other segments for special purposes.
  363. .PP
  364. A process terminates by calling
  365. .IR exits (2).
  366. A parent process may call
  367. .IR wait (2)
  368. to wait for some child to terminate.
  369. A string of status information
  370. may be passed from
  371. .I exits
  372. to
  373. .IR wait .
  374. A process can go to sleep for a specified time by calling
  375. .IR sleep (2).
  376. .PP
  377. There is a
  378. .I notification
  379. mechanism for telling a process about events such as address faults,
  380. floating point faults, and messages from other processes.
  381. A process uses
  382. .IR notify (2)
  383. to register the function to be called (the
  384. .IR "notification handler" )
  385. when such events occur.
  386. .SS Multithreading
  387. By calling
  388. .I rfork
  389. with the
  390. .B RFMEM
  391. bit set, a program may create several independently executing processes sharing the same
  392. memory (except for the stack segment, which is unique to each process).
  393. Where possible according to the ANSI C standard,
  394. the main C library works properly in multiprocess programs;
  395. .IR malloc ,
  396. .IR print ,
  397. and the other routines use locks (see
  398. .IR lock (2))
  399. to synchronize access to their data structures.
  400. The graphics library defined in
  401. .B <draw.h>
  402. is also multi-process capable; details are in
  403. .IR graphics (2).
  404. In general, though, multiprocess programs should use some form of synchronization
  405. to protect shared data.
  406. .PP
  407. The thread library, defined in
  408. .BR <thread.h> ,
  409. provides support for multiprocess programs.
  410. It includes a data structure called a
  411. .B Channel
  412. that can be used to send messages between processes,
  413. and coroutine-like
  414. .IR threads ,
  415. which enable multiple threads of control within a single process.
  416. The threads within a process are scheduled by the library, but there is
  417. no pre-emptive scheduling within a process; thread switching occurs
  418. only at communication or synchronization points.
  419. .PP
  420. Most programs using the thread library
  421. comprise multiple processes
  422. communicating over channels, and within some processes,
  423. multiple threads. Since Plan 9 I/O calls may block, a system
  424. call may block all the threads in a process.
  425. Therefore, a program that shouldn't block unexpectedly will use a process
  426. to serve the I/O request, passing the result to the main processes
  427. over a channel when the request completes.
  428. For examples of this design, see
  429. .IR ioproc (2)
  430. or
  431. .IR mouse (2).
  432. .SH SEE ALSO
  433. .IR nm (1),
  434. .IR 2l (1),
  435. .IR 2c (1)
  436. .SH DIAGNOSTICS
  437. Math functions in
  438. .I libc
  439. return
  440. special values when the function is undefined for the
  441. given arguments or when the value is not representable
  442. (see
  443. .IR nan (2)).
  444. .PP
  445. Some of the functions in
  446. .I libc
  447. are system calls and many others employ system calls in their implementation.
  448. All system calls return integers,
  449. with \-1 indicating that an error occurred;
  450. .IR errstr (2)
  451. recovers a string describing the error.
  452. Some user-level library functions also use the
  453. .I errstr
  454. mechanism to report errors.
  455. Functions that may affect the value of the error string are said to ``set
  456. .IR errstr '';
  457. it is understood that the error string is altered only if an error occurs.