]>
Commit | Line | Data |
---|---|---|
1 | @device(PostScript) | |
2 | @make(Manual) | |
3 | @style(FontFamily "Helvetica", Size 11) | |
4 | @style(hyphenation on) | |
5 | @style(indent 0) | |
6 | @style(leftmargin +4cm) | |
7 | @style(footnotes "") | |
8 | @modify(example,Size 10, below 1cm, above 1cm, leftmargin +3, rightmargin +0) | |
9 | @define(F, FaceCode F, Size 11, TabExport) | |
10 | @define(FunctionSection, leftmargin +1cm, rightmargin +1cm, size 10) | |
11 | @define(Function, leftmargin -.5cm, nofill, indent 0, break, group, | |
12 | above .6cm, below .4cm, blanklines kept, spread .7 line) | |
13 | @modify(HD1, Below .75cm, Above 1cm, indent -1cm) | |
14 | @modify(HD1A, Below .75cm, Above 1cm) | |
15 | @modify(HD2, Below .6cm, Above 1cm, indent -1cm) | |
16 | @modify(HD3, Below .6cm, Above 1cm) | |
17 | @modify(itemize, Below .5cm, Above .6cm) | |
18 | @modify(example, Below .5cm, Above .6cm) | |
19 | @modify(float, Below .5cm, Above .6cm) | |
20 | @begin(titlepage) | |
21 | @begin(titlebox) | |
22 | @majorheading(GDB C Library Reference Manual) | |
23 | @heading(Noah Mendelsohn) | |
24 | ||
25 | @end(titlebox) | |
26 | Document Version: 0.4 (DRAFT) | |
27 | For use with GDB Release: 0.4 | |
28 | This draft printed on: @value(Date) | |
29 | @copyrightnotice(MIT Project Athena) | |
30 | @end(titlepage) | |
31 | @Counter(ProgramNumber, Numbered <@1>, Referenced <@1>) | |
32 | @set(ProgramNumber=1) | |
33 | @PrefaceSection(Preface) | |
34 | ||
35 | GDB is a set of C library routines and related utilities which | |
36 | facilitate construction of network services. This preliminary version | |
37 | of the Library Reference Manual is based on specifications which were | |
38 | written before the code. In some cases, it refers to design decisions | |
39 | which had yet to be made at the time of writing, or uses terminology | |
40 | which is slightly inconsistent with the other GDB documentation. The | |
41 | tone of some of the descriptions is informal, reflecting debates over | |
42 | design philosophy which occured during development of GDB. | |
43 | Nevertheless, almost all of the services described herein are | |
44 | currently operational in Release 0.1 of GDB, and they conform very | |
45 | closely to their written specifications. This guide is intended | |
46 | primarily for reference. For a general introduction to programming | |
47 | with GDB, read the document titled "A Guide to Using GDB." Please | |
48 | report any discrepancies you discover in either document to the | |
49 | author. A more carefully edited version of this manual will accompany | |
50 | GDB Release 1. | |
51 | ||
52 | @PageHeading(Even, Right "@c[GDB Library Reference Manual]", | |
53 | Left "@c[@value(Page)]") | |
54 | @PageHeading(Odd, Right "@c[@value(Page)]", | |
55 | Left "@c[@Title(Chapter)]") | |
56 | ||
57 | @Chapter(Introduction) | |
58 | @Index[Introduction] | |
59 | ||
60 | This document is the program interface description for a collection of | |
61 | Unix@+[TM]@foot(@+[TM]Unix is a trademark of AT&T Bell Laboratories) | |
62 | library routines which provide transparent distributed support for | |
63 | network servers, and for relational databases in particular. The | |
64 | several libraries work together to implement a relational database | |
65 | which may be conveniently accessed from anywhere in a "Berkeley" Unix | |
66 | network, but the lower level libraries may themselves be useful for | |
67 | building other sorts of network services, or for | |
68 | transmitting other kinds of structured data. The database access | |
69 | and transmission services support communication between incompatible | |
70 | machine architectures; data conversions are done as necessary by the | |
71 | library routines. | |
72 | ||
73 | This document contains a separate section for each of the libraries. | |
74 | Interdependencies are noted in the sections. | |
75 | ||
76 | @chapter(Using the Libraries) | |
77 | ||
78 | The sections below outline the library services provided by GDB. | |
79 | Programs using GDB | |
80 | to access relational databases will use, directly or indirectly, the | |
81 | services of all of the GDB layers. Programs using GDB for local management | |
82 | of structured data or as a means of writing servers, clients, or other | |
83 | communicating programs may use only some of the layers. In any case, | |
84 | Every C main program | |
85 | that uses GDB should include the following: | |
86 | ||
87 | @begin(group) | |
88 | @begin(example) | |
89 | ||
90 | #include <stdio.h> | |
91 | #include "gdb.h" | |
92 | ||
93 | int | |
94 | main() | |
95 | { | |
96 | gdb_init(); | |
97 | /* | |
98 | * Once gdb_init has been called, the services of gdb are | |
99 | * available. gdb_init may be called only once. | |
100 | */ | |
101 | } | |
102 | @end(example) | |
103 | @end(group) | |
104 | ||
105 | Other source files should @f[#include "gdb.h"], but should @i[not] | |
106 | @index(gdb.h) | |
107 | invoke @f[gdb_init]. | |
108 | @index(gdb_init) | |
109 | ||
110 | If you are using GDB to access an Ingres database, then there are | |
111 | several other things you must do: | |
112 | ||
113 | @begin(itemize) | |
114 | @begin(multiple) | |
115 | Make sure RTI Ingres is installed at the server site where the data | |
116 | @index(RTI Ingres) | |
117 | @index(Ingres) | |
118 | is to be stored. | |
119 | @end(multiple) | |
120 | ||
121 | @begin(multiple) | |
122 | Make sure that there is an entry in the file named @f[/etc/services] | |
123 | @index(/etc/services) | |
124 | at both server and client sites for the service named gdb_db@index(gdb_db). | |
125 | The entries at the server and client should be identical. | |
126 | Talk to your system administrator if this is not the case. | |
127 | @i[Note: as of this writing, GDB does not check @f[/etc/services] when | |
128 | accessing Ingres, but soon it will!] | |
129 | @end(multiple) | |
130 | ||
131 | @begin(multiple) | |
132 | Make sure that the @f[dbserv] program supplied with GDB | |
133 | @index(dbserv) | |
134 | is started at the server site. | |
135 | @end(multiple) | |
136 | ||
137 | @end(itemize) | |
138 | ||
139 | Gdb produces two kinds of terminal output. Serious error messages, | |
140 | which are always directed to stderr, and other output, which are | |
141 | directed to the file indicated by the gdb_log global variable. | |
142 | Included in the latter are the results of functions like | |
143 | @f[print_relation]@index[print_relation], which are described below. | |
144 | Users wishing to redirect @f[gdb_log]@index[gdb_log] may open any | |
145 | stream of their choice and put the resulting FILE * variable into | |
146 | gdb_log after calling gdb_init. | |
147 | ||
148 | The remainder of this manual is taken with the definitions of the | |
149 | functions provided by GDB. The functions are organized by general | |
150 | category, but all are listed alphabetically in the index. Each | |
151 | section is prefaced by a brief introduction, followed by the function | |
152 | definitions themselves. In all the descriptions below, the | |
153 | pseudo-type @f[string]@Index[string] is used for @f[char *] in cases | |
154 | where a null terminated string is to be supplied. This is just a | |
155 | documentation convention, the type string is not defined in the | |
156 | libraries. Here is the description of the @f[gdb_init] function, the | |
157 | only one which has been introduced so far: | |
158 | ||
159 | @begin(functionsection) | |
160 | @begin(function) | |
161 | void | |
162 | @f[gdb_init]() | |
163 | @index[gdb_init] | |
164 | @end(function) | |
165 | ||
166 | Gdb_init initializes the data structures used by gdb. Gdb_init must be called | |
167 | once and only once prior to use of any other GDB services. No value is | |
168 | returned. | |
169 | @end(functionsection) | |
170 | ||
171 | @chapter(Database Manipulation) | |
172 | @Index(Database manipulation) | |
173 | ||
174 | This library provides most of the services of a shared, network wide, | |
175 | relational database. It is built on the structured object | |
176 | manipulation and transmission libraries described in Chapters | |
177 | @ref(structdata) and @ref(trans). A query, for example, returns a | |
178 | RELATION in the local process space. | |
179 | ||
180 | These routines have the following important characteristics: | |
181 | ||
182 | @begin(itemize) | |
183 | Access to databases stored on incompatible machines (e.g. RT/PC to | |
184 | Vax) is supported transparently. | |
185 | ||
186 | Pipelining of requests from client to server is encouraged. This | |
187 | maximizes overlap in processing and minimizes server swapouts between | |
188 | repeated requests, thereby improving performance. | |
189 | ||
190 | Requests proceed asynchronously with client execution, though | |
191 | synchronous interfaces are provided for applications where asynchrony | |
192 | is an unnecessary complication. Asynchronous processing is managed | |
193 | by appropriate interaction with the Berkeley 'select' mechanism; | |
194 | applications can be created which drive a user's terminal | |
195 | or other I/O devices while simultaneously retrieving the results | |
196 | of a database query. One important use of such overlap is to support | |
197 | abort operations (e.g. a screen menu selection to abort a long running | |
198 | query.) | |
199 | ||
200 | Multiple databases may be accessed simultaneously. If desired, these | |
201 | may reside at several sites. Using the asynchronous processing options, | |
202 | queries may be executed in parallel on the several databases. The | |
203 | same facilities may be used to open parallel connections to the same | |
204 | database, allowing parallel execution of independent operations. | |
205 | @end(itemize) | |
206 | ||
207 | Unfortunately, the syntax of a few of the actual library calls described | |
208 | herein is Ingres dependent. It is hoped that one day an effective | |
209 | cannonical form will be developed, and these routines replaced with a | |
210 | suite that might be supported using a variety of database engines. The | |
211 | Ingres dependency is isolated to a couple of routines. | |
212 | ||
213 | @section(Types Used for Database Manipulation) | |
214 | ||
215 | The types @f[RELATION, TUPLE, and FIELD_TYPE] are inherited from the | |
216 | structured data management libary (see Chapter @ref(structdata).) The | |
217 | following additional type is also used. | |
218 | ||
219 | @begin(table) | |
220 | @caption(Types used in Database Manipulation) | |
221 | @tabset(.75in, 2.5in) | |
222 | ||
223 | @\DATABASE@INDEX[DATABASE]@\A handle on an accessible database. | |
224 | @end(table) | |
225 | ||
226 | @Section(Routines) | |
227 | ||
228 | NOTE: See also the "Communications and Server Management" Section of | |
229 | this specification. This section contains only those functions | |
230 | particular to database manipulation. General facilities for | |
231 | starting operations and querying their status are found in the other | |
232 | section. | |
233 | ||
234 | @begin(functionsection) | |
235 | @begin(function) | |
236 | DBSTATUS | |
237 | @f[access_db](db_ident, &db_handle); | |
238 | @index[access_db] | |
239 | DATABASE db_handle; | |
240 | string db_ident; | |
241 | @end(function) | |
242 | ||
243 | Establishes a database context for future database calls. A successful | |
244 | accessdb call must be executed before any database operations can be done. | |
245 | The return code DB_OPEN indicates that the database was successfully accessed. | |
246 | A successful call to accessdb returns a local handle which must be | |
247 | supplied to subsequent library routines to indicate the database to be | |
248 | accessed. Most implementations support simultaneous access to several | |
249 | databases, but that is not required. The DB_TOO_MANY_ACCESSED error is | |
250 | raised when and if implementation defined limits are exceeded. Each | |
251 | database should be closed with a 'terminatedb' call when no longer needed. | |
252 | Failure to explicitly terminate databases may waste resources at the | |
253 | server, though most implementations will detect improper termination and | |
254 | do the necessary reclamation. | |
255 | ||
256 | The form of the db_ident string depends on the implementation. For | |
257 | example, in a network with nameservers, a single string such as | |
258 | 'partsdata' may suffice to identify a database on the network. When | |
259 | name resolution services are not available, a string of the form | |
260 | 'databasename@@site' may be required. There is a question of access | |
261 | rights and authorization for this operation. I'm hoping that we can | |
262 | eventually build on Kerberos, but there may be problems. Worst of all, | |
263 | we may have to re-invent Ingres' protection mechanism, which would | |
264 | involve a very detailed understanding of their operations. I hope not. | |
265 | ||
266 | @begin(function) | |
267 | int | |
268 | @f[start_accessing_db](op, db_ident, &db_handle); | |
269 | @index[start_accessing_db] | |
270 | OPERATION | |
271 | DATABASE db_handle; | |
272 | string db_ident; | |
273 | @end(function) | |
274 | ||
275 | Same as accessdb, but the program continues to execute (if possible) | |
276 | while the operation is sent to the server and performed. See | |
277 | 'complete_operation' and 'op_select.' All operations and queries are | |
278 | processed in fifo order. The value of db_handle is undefined until the | |
279 | operation_status(pending_operation) is OP_COMPLETE and the | |
280 | operation_result(pending_operation) is DB_OPEN. | |
281 | ||
282 | @begin(function) | |
283 | DBSTATUS | |
284 | @f[terminate_db](&db_handle); | |
285 | @index[terminate_db] | |
286 | DATABASE db_handle; | |
287 | @end(function) | |
288 | ||
289 | This routine reclaims server and client resources used to access the | |
290 | database and severs any connections which may no longer be needed. Data | |
291 | which has been retrieved and stored locally remains available. | |
292 | ||
293 | @begin(function) | |
294 | OPERATION | |
295 | @f[start_terminatedb](db_ident); | |
296 | @index[start_terminatedb] | |
297 | string db_ident; | |
298 | @end(function) | |
299 | ||
300 | Same as terminatedb, but the program continues to execute (if | |
301 | possible) while the operation is sent to the server and performed. | |
302 | See 'complete_operation' and 'op_select.' All operations and queries | |
303 | are processed in fifo order. | |
304 | ||
305 | @begin(function) | |
306 | OPERATION | |
307 | @f[DB_STATUS](db_handle); | |
308 | @index[DB_STATUS] | |
309 | DATABASE db_handle; | |
310 | @end(function) | |
311 | ||
312 | Returns the status of the specified database. Values returned are | |
313 | DB_OPEN@index[DB_OPEN], indicating that the database is available for use, | |
314 | or DB_CLOSED@index[DB_CLOSED], indicating that it is not. | |
315 | ||
316 | @begin(function) | |
317 | int | |
318 | @f[perform_db_operation](db_handle,request); | |
319 | @index[perform_db_operation] | |
320 | DATABASE db_handle; | |
321 | string request; | |
322 | @end(function) | |
323 | ||
324 | This routine may be used to perform any database operation which does | |
325 | not require structured data as an argument and which only returns a | |
326 | return code. In the case of Ingres, this covers all operations except | |
327 | retrieve. Requests are represented as null terminated strings. In | |
328 | other words, this library routine sends a simple string command to the | |
329 | server for execution and returns an integer return code. Any pending | |
330 | asynchronous operations on this database are completed before the | |
331 | supplied operation is attempted. | |
332 | ||
333 | @begin(function) | |
334 | int | |
335 | @f[db_query](db_handle, relation, query_string) | |
336 | @index[db_query] | |
337 | DATABASE db_handle; | |
338 | RELATION relation; | |
339 | string query_string; | |
340 | @end(function) | |
341 | ||
342 | Executes the query specified by query string, | |
343 | appending its result to the supplied relation. | |
344 | An integer return code is returned. OP_SUCCESS is returned for a | |
345 | successful query. The relation is unchanged unless the query | |
346 | succeeds. Note that it is possible to have a successful query (i.e. | |
347 | one which is well formed with respect to the database) which returns | |
348 | no data; such a query will return OP_SUCCESS leaving the relation unchanged. | |
349 | ||
350 | Query_string has the same form as an EQUEL query, except that the | |
351 | names of returned fields are enclosed in >* ....*< brackets (we can | |
352 | change the brackets to anything that won't conflict with Ingres | |
353 | syntax.) Note that the relation must be 'created' before it may be | |
354 | given to query_db. This is so we know typing information for | |
355 | constructing the actual database query. The caller may use sprintf or | |
356 | a similar function to prepare a query string containing variable data. | |
357 | The selected fields MUST match the names of fields in the relation. | |
358 | If not, a DB_BAD_FIELD_NAME error is raised before the query is | |
359 | executed. Null values are provided for tuple fields not retrieved by | |
360 | the query. | |
361 | ||
362 | The types of the referenced fields in the supplied relation must be | |
363 | drawn from a limited set of INTEGER_T, REAL_T, STRING_T and DATE_T types | |
364 | (the exact list will be provided in a later version of this | |
365 | specification document.) If not, a DB_BAD_FIELD_TYPE error is raised | |
366 | before the query is executed. The query will be constructed using the | |
367 | supplied types. If Ingres is incapable of doing the appropriate | |
368 | conversions upon retrieval, then a DB_CONVERSION_ERROR is returned. | |
369 | If the field type in the relation is STRING_T and Ingres succesfully | |
370 | converts the retrieved data to character form, then a null is appended | |
371 | iff there is room at the end. If the supplied field is too short, | |
372 | data is quietly dropped on the right end. The string is allocated by | |
373 | string_alloc. The | |
374 | string may be free'd with string_free, by the routine | |
375 | 'null_tuple_strings', or by the delete_relation routine. Normally, | |
376 | space is reclaimed automatically when the corresponding tuple or | |
377 | relation is freed. Fields not assigned by the query are set to null | |
378 | values. | |
379 | ||
380 | As specified, this routine is incapable of retrieving data of | |
381 | indeterminate structure, e.g. it cannot achieve the effect of an | |
382 | e.all retrieve in Ingres. This sort of function could be layered | |
383 | upon the base support suggested here, by first querying the Ingres | |
384 | structure database and then issuing the appropriate second query for | |
385 | the fields actually in the relation. This implementation is presumably | |
386 | slow, but I am reluctant to greatly complicate the design at this | |
387 | point. Another approach would be to add a special library routine | |
388 | db_query_relation which would create a relation, making assumptions | |
389 | about field representations for the fields actually retrieved. I'm | |
390 | inclined to put this off until we see the core of the library up and | |
391 | running. It would (probably) not involve a major restructure. | |
392 | ||
393 | @begin(function) | |
394 | int | |
395 | @f[start_performing_db_operation](operation, db_handle, | |
396 | @index[start_performing_db_operation] | |
397 | request); | |
398 | OPERATION operation; | |
399 | DATABASE db_handle; | |
400 | string request; | |
401 | @end(function) | |
402 | ||
403 | Same as perform_db_operation, but the program continues to execute (if | |
404 | possible) while the operation is sent to the server and performed. See | |
405 | 'operation_status, operation_result, complete_operation and | |
406 | op_select.' All operations and queries are processed in fifo order. | |
407 | Callers must insure that the request string | |
408 | remains valid until the operation completes (be careful about using local | |
409 | variables.) | |
410 | ||
411 | ||
412 | @begin(function) | |
413 | int | |
414 | @f[start_db_query](operation, db_handle, relation, | |
415 | @index[start_db_query] | |
416 | query_string) | |
417 | OPERATION operation; | |
418 | DATABASE db_handle; | |
419 | RELATION relation; | |
420 | string query_string; | |
421 | @end(function) | |
422 | ||
423 | Same as query_db, but the program continues to execute (if possible) | |
424 | while the operation is sent to the server and performed. See | |
425 | 'operation_status, operation_result, complete_operation and | |
426 | op_select.' The relation is undefined during the execution of this | |
427 | operation. It may not be referenced or free'd until the operation | |
428 | completes. All operations and queries are processed in fifo order. | |
429 | The value of the relation is indeterminate in the case of failure, | |
430 | but it is guaranteed to be of legal structure and self-consistent. | |
431 | Callers must insure that the query string | |
432 | remains valid until the operation completes (be careful about using local | |
433 | variables.) | |
434 | @end(functionsection) | |
435 | ||
436 | @chapter(Structured Data Management at a Single Site) | |
437 | @Index(Structured data management) | |
438 | @label(structdata) | |
439 | ||
440 | These routines provide a simple, limited facility for managing | |
441 | structured data on behalf of a single process. A basic datum is called | |
442 | a field, and it may be of arbitrary type (including user defined types.) | |
443 | Named fields may be collected into tuples, and lists of tuples may | |
444 | form relations. These constructs are used to represent the data | |
445 | retrieved from a relational database. A separate library (Chapter | |
446 | @ref(trans)) | |
447 | supports transmission of these data structures through a | |
448 | network. The typing scheme provided is sufficient to drive the | |
449 | transformations and re-alignment required when transmitting across | |
450 | incompatible machine architectures. It is NOT intended as a general | |
451 | purpose extension to the C language. | |
452 | ||
453 | @section(Type Definition and Manipulation) | |
454 | ||
455 | The information in this section is relavent to those users wishing to | |
456 | define their own types. User defined types are NOT necessary for | |
457 | typical database retrieval and update activities. Users desiring just | |
458 | those services need only know the names of built in system types, | |
459 | such as @f[INTEGER_T] and @f[STRING_T] which have direct counterparts in an | |
460 | Ingres database. @i[In the likely event that you have no need to | |
461 | define your own types, skip ahead now to section @ref(structypes).] | |
462 | ||
463 | Each datum or field managed by the system must be of some specified | |
464 | type. For each type, the system must have access to certain | |
465 | information (e.g. alignment restrictions) and to certain routines | |
466 | (initialize, encapsulate for transmission, etc.) Limited facilities to | |
467 | support user defined types are also helpful, since they allow such | |
468 | services as transmission across heterogeneous machines to be supported | |
469 | for arbitrary user data (this notion is stolen directly from ARGUS.) | |
470 | On the other hand, we don't want to tackle the many complicated | |
471 | problems inherent in a general solution to the dynamic typing problem. | |
472 | Instead, we employ the following simple, ad hoc mechanism, which seems | |
473 | to be sufficient for our needs. | |
474 | ||
475 | The system supports a set of types identified signed integers (e.g. | |
476 | type 1 might be STRING_T, type 2 might be DATE_T, etc.) Out of this | |
477 | name space, the first few starting from 0 are reserved for the system | |
478 | defined types, and the rest, up to GDB_MAX_TYPES, are available for | |
479 | dynamic assignment of user defined types. Appropriate pre-processor | |
480 | symbols, such as INTEGER_T, are provided in an include file for system | |
481 | types. | |
482 | ||
483 | For each type, certain information must be available to the system at | |
484 | execution time. This information is coded as a two dimensional array, | |
485 | each element of which holds either an integer, a pointer to a string, | |
486 | or a function pointer. One index selects the type, the other the | |
487 | property. For example, property number 6 of each type might be a code | |
488 | for its alignment requirement (4 for fullword, etc.). Using the | |
489 | example above, entry [2,6] in the type definition array would give the | |
490 | alignment rule for a field of type DATE_T. In certain cases, the | |
491 | information to be coded is a pointer to a routine. For example, a | |
492 | NULL value routine is provided for each type which can be used to initialize | |
493 | fields of that type. | |
494 | ||
495 | In order to create a user defined type, it is necessary to code | |
496 | functions for each of the necesary properties (e.g. the function which | |
497 | computes null values) and then use the "create_type" function to | |
498 | register the new type in the type tables. "create_type" returns the | |
499 | integer code assigned to the new type. WARNING: create_type is not | |
500 | yet implemented. | |
501 | ||
502 | @subsection(Information Required for Each Type) | |
503 | ||
504 | The simple mechanism described above is sufficient to encode the | |
505 | properties of each type. The information currently required is: | |
506 | ||
507 | @begin(itemize) | |
508 | LENGTH_PROPERTY: the length of the field | |
509 | ||
510 | ALIGNMENT_PROPERTY: an integer code for the alignment rule for the | |
511 | type (8 for doubleword, etc., may vary by machine type.) | |
512 | ||
513 | NULL_PROPERTY: a routine to initialize a null value of the type | |
514 | ||
515 | CODED_LENGTH_PROPERTY: a routine to calculate the length of the | |
516 | field when encoded for transmission. | |
517 | ||
518 | ||
519 | ENCODE_PROPERTY: a routine to encode the field for transmission | |
520 | ||
521 | DECODE_PROPERTY: a routine to decode tranmitted data into local | |
522 | representation | |
523 | ||
524 | FORMAT_PROPERTY: a routine to format the field (optional, for debugging) | |
525 | ||
526 | NAME_PROPERTY: a string name for the type. | |
527 | @end(itemize) | |
528 | ||
529 | For system defined types, this information is provided automatically by | |
530 | include files and libraries which initialize the system type definition | |
531 | array. Interface specifications for the various routines will be | |
532 | provided in a later version of this specification. For the moment, | |
533 | the code in source file @f[gdb_stype.c]@Index[gdb_stype.c] provides a | |
534 | useful model. | |
535 | ||
536 | @newpage | |
537 | @section(C Typedefs Relating to Data Structuring) | |
538 | @label(structypes) | |
539 | ||
540 | The following C types are defined in include files for use with the | |
541 | routines listed below. These should not be confused with types | |
542 | declared using the mechanisms above, which the C compiler knows nothing | |
543 | about. | |
544 | ||
545 | @begin(table) | |
546 | @caption(Typedefs for Data Structuring) | |
547 | @tabset(.75in, 2.5in) | |
548 | @\TUPLE_DESCRIPTOR@index[TUPLE_DESCRIPTOR]@\information needed to describe the structure | |
549 | @\@\of a given tuple. | |
550 | ||
551 | @\TUPLE@index[TUPLE]@\a handle on an actual tuple. This is always | |
552 | @\@\a pointer, and it may be manipulated | |
553 | @\@\accordingly (e.g. its length may be presumed | |
554 | @\@\small, and NULL is used for non-existent | |
555 | @\@\TUPLES.) | |
556 | ||
557 | @\RELATION@index[RELATION]@\a handle on an actual relation. This is always | |
558 | @\@\a pointer, and it may be manipulated | |
559 | @\@\accordingly. | |
560 | ||
561 | @\FIELD_TYPE@index[FIELD_TYPE]@\a type code for a field...generally | |
562 | @\@\represented as a signed integer (see above) | |
563 | @end(table) | |
564 | ||
565 | @section(Routines) | |
566 | ||
567 | (Note some of these may be implemented as macros. Where such | |
568 | implementation is presumed, the name is put in UPPERCASE. This | |
569 | allusion to Unix convention is meant to suggest that the associated | |
570 | operations are extremely fast, and that they are likely to suffer/gain | |
571 | from the semantic differences which distinguish macros from C | |
572 | functions. Note also that some of the macros contain define statements | |
573 | in C of the form @f[{}], these must be used without semicolon's or | |
574 | a syntax error will occur.) | |
575 | ||
576 | @begin(functionsection) | |
577 | @begin(function) | |
578 | TUPLE_DESCRIPTOR | |
579 | @f[create_tuple_descriptor](number_of_fields, name_list, | |
580 | @index(create_tuple_descriptor) | |
581 | type_list) | |
582 | string name_list[]; | |
583 | FIELD_TYPE type_list[]; | |
584 | int number_of_fields; | |
585 | @end(function) | |
586 | ||
587 | Allocates and fills in a tuple descriptor data structure. The | |
588 | descriptor records the number of fields in the tuple, the length in | |
589 | bytes of each field, and a pointer to the type descriptor of each | |
590 | field. Each field's offset is automatically assigned as the sum of | |
591 | the offsets of the fields preceeding it, adjusted according to the | |
592 | alignment condition found in the type descriptor. Note that the type | |
593 | named STRING_T has a reserved meaning in some contexts (see below). | |
594 | Specifically, string data is generally stored discontiguously from the | |
595 | tuple itself; the tuple holds only control information and a pointer | |
596 | to the string. Space for tuple descriptors is obtained using | |
597 | db_alloc. The tuple_descriptor reference count is set to 1. | |
598 | ||
599 | @begin(function) | |
600 | void | |
601 | @f[delete_tuple_descriptor](tuple_descriptor) | |
602 | @index(delete_tuple_descriptor) | |
603 | @end(function) | |
604 | ||
605 | Decrements the reference count, and if it goes to zero, | |
606 | releases the memory occupied by the tuple descriptor. | |
607 | ||
608 | @begin(function) | |
609 | TUPLE | |
610 | @f[create_tuple](tuple_descriptor) | |
611 | @index(create_tuple) | |
612 | @end(function) | |
613 | ||
614 | Allocates space for a new tuple, and initializes its description. The | |
615 | values of fields in the tuple are not initialized. String types are | |
616 | not distinguished in this operation; no space is allocated for the | |
617 | target of a string pointer. The reference count of the tuple | |
618 | descriptor is incremented. | |
619 | ||
620 | @begin(function) | |
621 | void | |
622 | @f[delete_tuple](tuple) | |
623 | @index[delete_tuple] | |
624 | TUPLE tuple; | |
625 | @end(function) | |
626 | ||
627 | Deallocates the space for the specified tuple. Neither the tuple descriptor | |
628 | nor any of the string data which may be referenced by the tuple is | |
629 | deleted. The reference count of the tuple descriptor is decremented, | |
630 | and if necessary, the descriptor is deleted too. | |
631 | ||
632 | @begin(function) | |
633 | void | |
634 | @f[initialize_tuple](tuple) | |
635 | @index[initialize_tuple] | |
636 | TUPLE tuple; | |
637 | @end(function) | |
638 | ||
639 | Sets each field in a tuple to its null value. | |
640 | ||
641 | @begin(function) | |
642 | void | |
643 | @f[null_tuple_strings](tuple) | |
644 | @index(null_tuple_strings) | |
645 | TUPLE tuple; | |
646 | @end(function) | |
647 | ||
648 | Reclaims the space for all fields in the tuple whose type is STRING_T. | |
649 | The value of the string itself is set to uninitialized. The sequence | |
650 | "null_tuple_strings(t); delete_tuple(t);" may be used to reclaim all | |
651 | the space used for a tuple containing string fields. | |
652 | ||
653 | @begin(function) | |
654 | RELATION | |
655 | @f[create_relation](tuple_descriptor); | |
656 | @index[create_relation] | |
657 | TUPLE_DESCRIPTOR tuple_descriptor; | |
658 | @end(function) | |
659 | ||
660 | Creates an empty relation. Tuples subsequently added to the relation | |
661 | must contain the fields described in the tuple descriptor at the time | |
662 | the relation is created. Not sure yet whether this will be checked. | |
663 | May just create a generalized relation in which each tuple is | |
664 | self_describing and the consistent case is viewed as a subset. | |
665 | The tuple descriptor reference count is incremented. | |
666 | ||
667 | ||
668 | @begin(function) | |
669 | int | |
670 | @f[delete_relation](rel); | |
671 | @index[delete_relation] | |
672 | RELATION rel; | |
673 | @end(function) | |
674 | ||
675 | Reclaims the space for the specified relation, which should not be | |
676 | used again by the caller. All tuples are deleted, along with any strings | |
677 | which have been allocated in the tuples. The caller must insure that the | |
678 | contents of any string fields are self consistent, i.e. if the string is | |
679 | non-null, then it must refer to data which was properly allocated by gdb. | |
680 | The tuple descriptor reference count is decremented, and if necessary, | |
681 | the descriptor is deleted. | |
682 | ||
683 | @begin(function) | |
684 | void | |
685 | @f[ADD_TUPLE_TO_RELATION ]@index[ADD_TUPLE_TO_RELATION](relation, tuple) | |
686 | ||
687 | void | |
688 | @f[ADD_TUPLE_AFTER_TUPLE] (relation, new_tuple, | |
689 | @index[ADD_TUPLE_AFTER_TUPLE] | |
690 | previous_tuple) | |
691 | ||
692 | RELATION relation; | |
693 | TUPLE tuple, new_tuple, previous_tuple; | |
694 | @end(function) | |
695 | ||
696 | These operations insert a new tuple into a relation. They do NOT | |
697 | allocate storage for the tuple, because there may be times when it is | |
698 | convenient to insert an existing tuple into a relation. These | |
699 | routines will probably be implemented as macros, hence the uppercase | |
700 | names. ADD_TUPLE_TO_RELATION places the new tuple after all those | |
701 | already in the relation. Each tuple may in in only one relation at a | |
702 | time. This routine may or may not check for conformity between | |
703 | the description of the tuple and the description of the relation. A | |
704 | given tuple may be in only one relation at a time; this is not | |
705 | checked. Note: to insert a tuple as the first one in the relation, | |
706 | provide the relation pointer as the previous tuple, e.g. | |
707 | ADD_TUPLE_AFTER_TUPLE(r, t, (TUPLE)r). | |
708 | ||
709 | @begin(function) | |
710 | TUPLE | |
711 | @f[REMOVE_TUPLE_FROM_RELATION](relation, tuple) | |
712 | @index[REMOVE_TUPLE_FROM_RELATION] | |
713 | RELATION relation; | |
714 | TUPLE tuple; | |
715 | @end(function) | |
716 | ||
717 | Removes the designated tuple from the relation (this function may | |
718 | be implemented to remove the tuple from whichever relation it is in, | |
719 | or it may check which relation it is in, or it may presume that the | |
720 | correct relation is specified. No checking need be done; caller | |
721 | is responsible for insuring that the tuple is indeed in the | |
722 | specified relation.) The tuple is not de-allocated, merely removed | |
723 | from the relation. It may subsequently be inserted in a different | |
724 | relation. | |
725 | ||
726 | ||
727 | @begin(function) | |
728 | RELATION | |
729 | @f[tuples_in_relation](rel); | |
730 | @index[tuples_in_relation] | |
731 | RELATION rel; | |
732 | @end(function) | |
733 | ||
734 | Returns a count of the tuples in the supplied relation. | |
735 | ||
736 | @begin(function) | |
737 | TUPLE_DESCRIPTOR | |
738 | @f[DESCRIPTOR_FROM_TUPLE](tuple) | |
739 | @index[DESCRIPTOR_FROM_TUPLE] | |
740 | ||
741 | TUPLE_DESCRIPTOR | |
742 | @f[DESCRIPTOR_FROM_RELATION](relation) | |
743 | ||
744 | @index[DESCRIPTOR_FROM_RELATION] | |
745 | TUPLE tuple; | |
746 | RELATION relation; | |
747 | @end(function) | |
748 | ||
749 | Given a tuple or relation, return the descriptor of its entries. | |
750 | ||
751 | @begin(function) | |
752 | int | |
753 | @f[field_index](tuple_descriptor, field_name) | |
754 | @index[field_index] | |
755 | TUPLE_DESCRIPTOR tuple_descriptor; | |
756 | string field_name; | |
757 | @end(function) | |
758 | ||
759 | Given a tuple descriptor and the string name of a field in the tuple, | |
760 | this routine returns the 0 relative index of the field in the tuple. | |
761 | If the named field is not in the tuple, -1 is returned. | |
762 | ||
763 | @begin(function) | |
764 | (?? *) | |
765 | @f[FIELD_FROM_TUPLE](tuple, field_index); | |
766 | @index[FIELD_FROM_TUPLE] | |
767 | TUPLE tuple; | |
768 | int field_index; | |
769 | string field_name; | |
770 | @end(function) | |
771 | ||
772 | Given the relative index of a field in a tuple (0 origin), return a | |
773 | pointer to the first byte of data in the field. See also @f[field_index]. | |
774 | ||
775 | @begin(function) | |
776 | int | |
777 | @f[FIELD_OFFSET_IN_TUPLE](tuple_descriptor, field_index); | |
778 | @index[FIELD_OFFSET_IN_TUPLE] | |
779 | ||
780 | FIELD_TYPE | |
781 | @f[FIELD_TYPE_IN_TUPLE](tuple_descriptor, field_index); | |
782 | ||
783 | @index[FIELD_TYPE_IN_TUPLE] | |
784 | @end(function) | |
785 | ||
786 | Given the type descriptor for an entire tuple and the name of a field | |
787 | in the tuple, these routines return the byte offset, and the | |
788 | field_type of the named field in the tuple. Their results are | |
789 | undefined in the case where the field_index is negative or too large. | |
790 | Note, the offset returned is from the start of the tuple data, NOT from | |
791 | the start of the tuple itself. To address the field, the construction: | |
792 | (tup->data)+offset gives the true addresss of the first byte of the field. | |
793 | This may change in the future, since it seems to require an unnecessary | |
794 | knowledge of the tuple structure on the part of the programmer. | |
795 | ||
796 | @begin(function) | |
797 | TUPLE | |
798 | @f[FIRST_TUPLE_IN_RELATION](relation) | |
799 | @index[FIRST_TUPLE_IN_RELATION] | |
800 | ||
801 | TUPLE | |
802 | @f[NEXT_TUPLE_IN_RELATION](relation,tuple) | |
803 | @index[NEXT_TUPLE_IN_RELATION] | |
804 | ||
805 | TUPLE | |
806 | @f[PREV_TUPLE_IN_RELATION](relation,tuple) | |
807 | @index[PREV_TUPLE_IN_RELATION] | |
808 | ||
809 | RELATION relation; | |
810 | TUPLE tuple; | |
811 | @end(function) | |
812 | ||
813 | Returns tuples from a relation relative to the order in which they were | |
814 | inserted. NULL is returned for the successor of the last tuple or the | |
815 | predecessor of the first tuple in a relation. | |
816 | ||
817 | @begin(function) | |
818 | void | |
819 | @f[print_relation](name, relation) | |
820 | @index[print_relation] | |
821 | ||
822 | void | |
823 | @f[print_tuple](name, tuple) | |
824 | ||
825 | @index[print_tuple] | |
826 | ||
827 | void | |
828 | @f[print_tuple_descriptor](name, desc) | |
829 | @index[print_tuple_descriptor] | |
830 | ||
831 | string name; | |
832 | RELATION relation; | |
833 | TUPLE tuple; | |
834 | TUPLE_DESCRIPTOR desc; | |
835 | @end(function) | |
836 | ||
837 | These routines format the contents of the specified relation or tuple | |
838 | and write the results to the gdb logging file descriptor. The | |
839 | supplied name, an ordinary C null terminated string, is used to label | |
840 | the printed entry in the log. These routines are intended primarily | |
841 | for debugging. | |
842 | @end(functionsection) | |
843 | ||
844 | @chapter(Structured Data Transmission Services) | |
845 | @index(Data transmission) | |
846 | @index(Transmission of data) | |
847 | @index(Structured data transmission) | |
848 | @label(trans) | |
849 | ||
850 | These services are used to move structured data between communicating | |
851 | programs. To provide some context for this discussion, we summarize | |
852 | here the basic techniques used to create servers and clients, and | |
853 | introduce the use of OPERATIONS for handling asynchronous activities. | |
854 | This discussion partially duplicates that of Chapter | |
855 | @ref(serverclient), which is devoted to server/client management, and | |
856 | general techniques for managing asynchronous operations in GDB. The | |
857 | emphasis in this chapter is on transmission of structured data. | |
858 | ||
859 | @section(Background) | |
860 | ||
861 | Two styles of communicating program are supported: peer-to-peer, in which | |
862 | the two sides of the connection are considered to be symmetrical, and | |
863 | client/server, in which a server is pre-started, awaiting connections from | |
864 | one or more clients. The following types are used by the structured data | |
865 | transmission services: | |
866 | ||
867 | @begin(itemize) | |
868 | ||
869 | @begin(multiple) | |
870 | CONNECTION | |
871 | ||
872 | represents a communication path to some other program using | |
873 | GDB. Usually, this is a network communication path between | |
874 | programs on different machines. Connections may | |
875 | be closed explictly by issueing a "sever_connection", and they | |
876 | are implicitly closed when the process owning the | |
877 | connection exits. | |
878 | @end(multiple) | |
879 | ||
880 | @begin(multiple) | |
881 | OPERATION | |
882 | ||
883 | GDB is capable of managing asynchronous activities on its | |
884 | CONNECTIONS. When a program wishes to do asynchronous | |
885 | communication it creates an OPERATION to represent the state | |
886 | of the asynchronous activity. GDB provides functions and | |
887 | macros for manipulating OPERATIONS. For example, | |
888 | OP_DONE(operation) returns true iff the operation has | |
889 | completed. | |
890 | @end(multiple) | |
891 | @end(itemize) | |
892 | ||
893 | @section(Service and Network Addresses) | |
894 | ||
895 | In the current implementation, the address of a GDB program | |
896 | running on the network has the form: | |
897 | ||
898 | @begin(example) | |
899 | "hostname:servicename" | |
900 | @end(example) | |
901 | ||
902 | where hostname is the internet name of the host on which the program | |
903 | is running, and servicename is the name of the service as registered | |
904 | in @f[/etc/services]@index[/etc/services]. Services should be of type | |
905 | tcp. An alternate form of servicename is #portnumber, where | |
906 | portnumber is the integer number of the Berkeley port to | |
907 | be used for the service. Use of explicit port numbers is | |
908 | discouraged, except for testing. Examples: | |
909 | "myhost:dbserver" or "yourhost:#1234". All addresses are | |
910 | represented as null terminated strings in C. | |
911 | ||
912 | ||
913 | ||
914 | @section(Establishing Communication) | |
915 | ||
916 | As noted above, there are two general styles of communicating | |
917 | programs. Peer-to-peer communication is started by use of the | |
918 | following function. These services and other related routines are | |
919 | fully documented in Chapter @ref(serverclient). The discussion here | |
920 | is intended to introduce the GDB services which transmit structured | |
921 | data. | |
922 | ||
923 | @begin(functionsection) | |
924 | ||
925 | @begin(function) | |
926 | CONNECTION | |
927 | @f[start_peer_connection](service_address) | |
928 | @index[start_peer_connection] | |
929 | string service_address; | |
930 | @end(function) | |
931 | ||
932 | Creates a connection to a peer at the designated address (see service and | |
933 | network addresses above.) Either peer may start first. This routine will | |
934 | hang indefinitely waiting for its peer, unless a fatal error is | |
935 | encountered. There is currently no asynchronous form of this service. | |
936 | NULL is returned in case of an error. Messages describing some errors are | |
937 | written to stderr, but otherwise, there is currently no way for the program | |
938 | to determine why a failure occurred. | |
939 | @end(functionsection) | |
940 | ||
941 | Clients may request a connection to a server by using the following | |
942 | function: | |
943 | ||
944 | @begin(functionsection) | |
945 | @begin(function) | |
946 | CONNECTION | |
947 | @f[start_server_connection](service_address, parms) | |
948 | @index[start_server_connection] | |
949 | string service_address; | |
950 | string parms; | |
951 | @end(function) | |
952 | ||
953 | Rules are the same as for start_peer_connection except: (1) The server must be | |
954 | started and listening at the time the connection is attempted, or this | |
955 | request will fail. (2) The supplied parms are made available to the | |
956 | server, which may use them in deciding whether to accept the connection or | |
957 | how to process it. This request will generally not hang for very long, but | |
958 | it does set up a socket and do a limited amount of communication | |
959 | synchronously. Typical delays on a local network with no gateways are a | |
960 | fraction of a second. Note that GDB supports several styles of server | |
961 | (e.g. forking and non-forking), but clients connect to and communicate with | |
962 | all of them in the same manner. | |
963 | ||
964 | @end(functionsection) | |
965 | ||
966 | The techniques for creating servers are described in Chapter | |
967 | @ref(serverclient). | |
968 | ||
969 | @section(Synchronous Communication) | |
970 | ||
971 | GDB is capable of transmitting data of any of the types described in | |
972 | Chapter @ref(structdata). This means that the services below may be | |
973 | used to send data as simple as a single integer, or as complex as an | |
974 | entire relation with all of its tuples and fields. In all cases, data | |
975 | is automatically converted to the appropriate representation when it | |
976 | is transmitted between machines of different architecture. | |
977 | ||
978 | @begin(functionsection) | |
979 | ||
980 | @begin(function) | |
981 | int | |
982 | @f[send_object](con, obj_ptr, type_id) | |
983 | @index[send_object] | |
984 | CONNECTION con; | |
985 | char *obj_ptr; | |
986 | FIELD_TYPE type_id; | |
987 | @end(function) | |
988 | ||
989 | Synchronously transmits the specified data on the connection con. Obj_ptr | |
990 | must be the address of the object to be sent, and type_id must indicate the | |
991 | type of the object to be sent. The final status of the transmit operation | |
992 | is returned. In general, OP_SUCCESS indicates success, OP_CANCELLED | |
993 | indicates an error. OP_CANCELLED generally implies that the corresponding | |
994 | connection has broken and should be severed. Examples: | |
995 | ||
996 | @begin(example) | |
997 | rc = send_object(server, &my_int, INTEGER_T); | |
998 | /* send an integer */ | |
999 | rc = send_object(peer, &tuple, TUPLE_T); | |
1000 | /* send a tuple */ | |
1001 | rc = send_object(peer, &rel, RELATION_T); | |
1002 | /* send a relation */ | |
1003 | @end(example) | |
1004 | ||
1005 | @begin(function) | |
1006 | int | |
1007 | @f[receive_object](con, obj_ptr, type_id) | |
1008 | @index[receive_object] | |
1009 | CONNECTION con; | |
1010 | char *obj_ptr; | |
1011 | FIELD_TYPE type_id; | |
1012 | @end(function) | |
1013 | ||
1014 | Synchronously receives the specified data on the connection con. Obj_ptr | |
1015 | must be the address of the object to be received, and type_id must indicate the | |
1016 | type of the object. The final status of the receive operation | |
1017 | is returned. In general, OP_SUCCESS indicates success, OP_CANCELLED | |
1018 | indicates an error. OP_CANCELLED generally implies that the corresponding | |
1019 | connection has broken and should be severed. Examples: | |
1020 | ||
1021 | @begin(example) | |
1022 | rc = receive_object(server, &my_int, INTEGER_T); | |
1023 | /* receive integer */ | |
1024 | rc = receive_object(peer, &tuple, TUPLE_T); | |
1025 | /* receive a tuple */ | |
1026 | rc = receive_object(peer, &rel, RELATION_T); | |
1027 | /* receive relation */ | |
1028 | @end(example) | |
1029 | ||
1030 | Note that receipt of certain structured objects implies that local memory | |
1031 | is dynamically allocated to hold the newly received objects. The system | |
1032 | defined types for which this is the case incude: TUPLE_T, RELATION_T, | |
1033 | TUPLE_DESCRIPTOR_T, and STRING_T. TUPLE_DATA_T implies memory allocation | |
1034 | only if the fields in the tuple require it. | |
1035 | @end(functionsection) | |
1036 | ||
1037 | @section(Asynchronous communication) | |
1038 | ||
1039 | GDB provides a general architecture for executing asynchronous | |
1040 | communication activities on a connection. Several asynchronous operations | |
1041 | are provided with the system, and sophisticated users can write their own | |
1042 | (it's a little tricky, but it can be done.) Most users will find the | |
1043 | supplied operations to be sufficient. | |
1044 | ||
1045 | Each asynchronous activity is known as an operation. Programmers using the | |
1046 | asynchronous capabilities of GDB must declare an OPERATION to keep track of | |
1047 | the state of each asynchronous activity. For example: | |
1048 | ||
1049 | @begin(example) | |
1050 | OPERATION send_op1, send_op2, receive_op; | |
1051 | @end(example) | |
1052 | ||
1053 | declares 3 operations. Before an operation can be used it must be | |
1054 | "created": | |
1055 | ||
1056 | @begin(example) | |
1057 | send_op1 = create_operation(); | |
1058 | @end(example) | |
1059 | ||
1060 | The newly allocated 'operation' may then be used to track the state of an | |
1061 | asynchronous activity, and if desired, it may later be reset and re-used | |
1062 | without being re-created. These techniques lower the cost of doing | |
1063 | repeated asynchronous activities. Many applications can create all their | |
1064 | operations at start-up, resetting and re-using them as necessary. | |
1065 | ||
1066 | Each of the asynchronous routines described below takes an OPERATION as an | |
1067 | argument. In each case, the supplied operation should be newly created or | |
1068 | reset, and in no case may it be in use by another routine; each | |
1069 | OPERATION tracks the state of one activity at a time. The simplest way to | |
1070 | synchronize asynchronous activity is with the 'complete_operation' | |
1071 | function: | |
1072 | ||
1073 | @begin(example) | |
1074 | complete_operation@index[complete_operation](send_op1); | |
1075 | complete_operation(send_op2); | |
1076 | @end(example) | |
1077 | ||
1078 | Note that GDB is coded to maximize throughput and avoid deadlock when | |
1079 | several activities are proceeding simultaneously. For example, the two | |
1080 | calls shown above can be done in either order, since send_op2 progresses | |
1081 | even while waiting for completion of send_op1. A simple way to do | |
1082 | parallel communication on several connections is to start each of the | |
1083 | activities and then wait for completion of all of them. Each progresses as | |
1084 | fast as possible and as nearly in parallel as GDB can manage. GDB uses | |
1085 | Berkeley 'select' to avoid spinning when work cannot proceed. | |
1086 | ||
1087 | In addition to 'complete_operation', several routines are provided which | |
1088 | can wait for any of a list of operations to complete, and which can combine | |
1089 | a GDB wait with the facilities of a Berkeley 'select' on fd's not | |
1090 | controlled by GDB. These features are documented at the end of this | |
1091 | chapter. | |
1092 | ||
1093 | Operations executed on a given half connection are executed in FIFO order, | |
1094 | unless specifically indicated to the contrary. (A half connection refers | |
1095 | to either the inbound or outbound stream of a given connection; send and | |
1096 | receive requests are queued independently.) A synchronous request as | |
1097 | executed only after the completion of all prior asyncrhonous requests on | |
1098 | the same half connection. | |
1099 | ||
1100 | An operation which is attempted on a failed connection, or an operation | |
1101 | which encounters a connection error during execution returns the status | |
1102 | @f[OP_CANCELLED]. Severing a connection implicitly cancels any operations | |
1103 | which are queued on that connection. | |
1104 | ||
1105 | GDB generally makes as much progress as it can whenever the | |
1106 | communication layer is given control. For example, whenever a new | |
1107 | operation is queued on a given connection, all connections are allowed | |
1108 | to proceed as far as they can. When a complete_operation is issued, | |
1109 | all activities proceed while awaiting completion of the specified | |
1110 | operation. However, gdb only progresses when explictly given control; | |
1111 | it does not use SIGIO@index[SIGIO]. For this reason, GDB programs | |
1112 | should hang in a 'complete_operation' or in one of the forms of | |
1113 | 'op_select' when there is no work to be done, as this will allow GDB | |
1114 | activities to proceed. If the user issues his/her own select, sleep | |
1115 | or a wait, GDB activities may be delayed. | |
1116 | ||
1117 | @subsection(Asynchronous Data Transmission) | |
1118 | @label(async) | |
1119 | @index(Asynchronous data transmission) | |
1120 | ||
1121 | The following routines are similar to send_object and receive_object, but | |
1122 | they do their work asynchronously. | |
1123 | ||
1124 | @begin(functionsection) | |
1125 | @begin(function) | |
1126 | int | |
1127 | @f[start_sending_object](op, con, obj_ptr, type_id) | |
1128 | @index[start_sending_object] | |
1129 | OPERATION op; | |
1130 | CONNECTION con; | |
1131 | char *obj_ptr; | |
1132 | FIELD_TYPE type_id; | |
1133 | @end(function) | |
1134 | ||
1135 | Asynchronously transmits the specified data on the connection con. | |
1136 | Obj_ptr must be the address of the object to be sent, and type_id must | |
1137 | indicate the type of the object to be sent. The final status | |
1138 | (OP_STATUS(OP)) of the transmit operation is not available until the | |
1139 | operation 'op' completes. In general, OP_COMPLETE indicates success, | |
1140 | OP_CANCELLED indicates an error. OP_CANCELLED generally implies that | |
1141 | the corresponding connection has broken and should be severed. | |
1142 | OP_RESULT of a successful transmission will be OP_SUCCESS. | |
1143 | Example: | |
1144 | ||
1145 | @begin(example) | |
1146 | op1 = create_operation(); | |
1147 | op2 = create_operation(); | |
1148 | op3 = create_operation(); | |
1149 | start_sending_object(op1, server, &my_int, INTEGER_T); | |
1150 | start_sending_object(op2, peer, &tuple, TUPLE_T); | |
1151 | start_sending_object(op3, peer, &rel, RELATION_T); | |
1152 | compete_operation(op1); | |
1153 | compete_operation(op2); | |
1154 | compete_operation(op3); | |
1155 | if (OP_STATUS(op1) == OP_CANCELLED || | |
1156 | OP_STATUS(op2) == OP_CANCELLED || | |
1157 | OP_STATUS(op2) == OP_CANCELLED) | |
1158 | printf("Couldn't do it\n"); | |
1159 | @end(example) | |
1160 | ||
1161 | @begin(function) | |
1162 | int | |
1163 | @f[start_receiving_object](op, con, obj_ptr, type_id) | |
1164 | @index[start_receiving_object] | |
1165 | OPERATION op; | |
1166 | CONNECTION con; | |
1167 | char *obj_ptr; | |
1168 | FIELD_TYPE type_id; | |
1169 | @end(function) | |
1170 | ||
1171 | Asynchronously receives the specified data on the connection con. | |
1172 | Obj_ptr must be the address of the object to be received, and type_id | |
1173 | must indicate the type of the object. The final status of the receive | |
1174 | operation is not available until the operation 'op' completes. In | |
1175 | general, an OP_STATUS ofOP_COMPLETE indicates success, OP_CANCELLED | |
1176 | indicates an error. OP_CANCELLED generally implies that the | |
1177 | corresponding connection has broken and should be severed. OP_RESULT | |
1178 | of a successful receipt will be OP_SUCCESS. Example: | |
1179 | ||
1180 | @begin(example) | |
1181 | op1 = create_operation(); | |
1182 | op2 = create_operation(); | |
1183 | op3 = create_operation(); | |
1184 | start_receiving_object(op1, server, &my_int, INTEGER_T); | |
1185 | start_receiving_object(op2, peer, &tuple, TUPLE_T); | |
1186 | start_receiving_object(op3, peer, &rel, RELATION_T); | |
1187 | compete_operation(op1); | |
1188 | compete_operation(op2); | |
1189 | compete_operation(op3); | |
1190 | if (OP_STATUS(op1) == OP_CANCELLED || | |
1191 | OP_STATUS(op2) == OP_CANCELLED || | |
1192 | OP_STATUS(op2) == OP_CANCELLED) | |
1193 | printf("Couldn't do it\n"); | |
1194 | @end(example) | |
1195 | @end(functionsection) | |
1196 | ||
1197 | @chapter(Memory Management) | |
1198 | @Index(Memory management) | |
1199 | @Index(Storage allocation) | |
1200 | ||
1201 | The following routines are provided to encapsulate calls to memory | |
1202 | management services for all of the libraries defined in this | |
1203 | specification. Early implementations will just use malloc, but | |
1204 | more sophisticated techniques might be used in the future. | |
1205 | ||
1206 | @begin(functionsection) | |
1207 | @begin(function) | |
1208 | (?? *) | |
1209 | @f[db_alloc](bytes) | |
1210 | @index[db_alloc] | |
1211 | int bytes; | |
1212 | @end(function) | |
1213 | ||
1214 | Allocates the number of bytes requested and returns the corresponding | |
1215 | pointer. The allocated space is always word aligned. | |
1216 | ||
1217 | @begin(function) | |
1218 | void | |
1219 | @f[db_free](ptr, bytes) | |
1220 | @index[db_free] | |
1221 | (??) *p; | |
1222 | int bytes; | |
1223 | @end(function) | |
1224 | ||
1225 | De-allocates the memory pointed to by ptr. Some implementations by | |
1226 | ignore the supplied size, requiring that ptr be a value obtained from | |
1227 | db_alloc. Others may support more flexible pool management for | |
1228 | which the size will be useful. | |
1229 | @end(functionsection) | |
1230 | ||
1231 | @section(Overriding the default memory management routines) | |
1232 | ||
1233 | Two global function pointers are provided which point to the allocation | |
1234 | and free routines which are actually called when db_alloc and db_free | |
1235 | are used. A user of gdb may supply his or her own memory management | |
1236 | routines by replacing the supplied pointers with pointers to new routines. | |
1237 | The global variables to be changed are: | |
1238 | ||
1239 | @begin(format) | |
1240 | @tabset(.75in, 2.5in) | |
1241 | @\@f[gdb_amv]@index[gdb_amv]@\vector to the allocate memory routine | |
1242 | ||
1243 | @\@f[gdb_fmv]@index[gdb_fmv]@\vector to the free memory routine | |
1244 | @end(format) | |
1245 | ||
1246 | The pointers should be to routines matching the specification for | |
1247 | @f[db_alloc]@index[db_alloc] and @f[db_free]@index[db_free] above. | |
1248 | The pointers should be changed prior to calling | |
1249 | gdb_init@index[gdb_init] to insure that all memory allocated by gdb is | |
1250 | obtained using the new services. | |
1251 | ||
1252 | @chapter(String Management) | |
1253 | @Index(String management) | |
1254 | ||
1255 | These routines provide allocation and de-allocation services for | |
1256 | STRING_T data. Like db_alloc and db_free, their | |
1257 | primary raison d'etre is to centralize creation and deletion of | |
1258 | strings. | |
1259 | ||
1260 | The only special TYPEDEF used for string management is @f[STRING]. | |
1261 | STRING describes a datum of GDB type STRING_T. This must contain | |
1262 | sufficient information to record the location of the data | |
1263 | (e.g. a pointer) and the length with which the data | |
1264 | was allocated (which need not be the length of null | |
1265 | terminated data actually contained in the field.) | |
1266 | ||
1267 | @section(Routines) | |
1268 | ||
1269 | @begin(functionsection) | |
1270 | @begin(function) | |
1271 | int | |
1272 | @f[string_alloc](stringp,bytes); | |
1273 | @index[string_alloc] | |
1274 | STRING *stringp; | |
1275 | int bytes; | |
1276 | @end(function) | |
1277 | ||
1278 | Allocates memory to contain a string of the specified length | |
1279 | and returns the associated string handle. The supplied length should | |
1280 | include space for a terminating null if one is to be used, but these | |
1281 | libraries make no such presumption. A null is stored in the first byte | |
1282 | of the returned data area. | |
1283 | ||
1284 | @begin(function) | |
1285 | void | |
1286 | @f[string_free](stringp); | |
1287 | @index[string_free] | |
1288 | STRING *stringp; | |
1289 | ||
1290 | De-allocates the supplied string. The length given must match that used | |
1291 | to allocate the space with string_alloc (which need not be the same as | |
1292 | the length of the null terminated data currently in the string.) | |
1293 | @end(function) | |
1294 | ||
1295 | @begin(function) | |
1296 | (char *) | |
1297 | @f[STRING_DATA](string) | |
1298 | @index[STRING_DATA] | |
1299 | STRING string; | |
1300 | @end(function) | |
1301 | ||
1302 | A macro which returns the pointer to the first byte of the referenced | |
1303 | string. NULL is returned for an uninitialized string. | |
1304 | ||
1305 | @begin(function) | |
1306 | int | |
1307 | @f[MAX_STRING_SIZE](string) | |
1308 | @index[MAX_STRING_SIZE] | |
1309 | STRING string; | |
1310 | @end(function) | |
1311 | ||
1312 | A macro which returns the total number of bytes available in the string | |
1313 | (which may be greater than the length of any null terminated data which | |
1314 | happens to reside there at the moment.) | |
1315 | @end(functionsection) | |
1316 | ||
1317 | @Chapter(Server and Communications Management) | |
1318 | @label(serverclient) | |
1319 | @Index(Server and communication management) | |
1320 | ||
1321 | These are routines whose purpose is to facilitate the creation of shared, | |
1322 | centralized, or peer-to-peer network services in a Berkeley Unix system. | |
1323 | At the server, they manage the creation of sub-processes for a given client | |
1324 | or sub-service, and the allocation and use of sockets for communication to | |
1325 | the clients. A corresponding set of routines is used by clients to request | |
1326 | and maintain sessions with various services. | |
1327 | ||
1328 | The following types are used for server and communications management: | |
1329 | ||
1330 | @begin(table) | |
1331 | @caption(Types used in Server and Communications Management) | |
1332 | @tabset(.75in, 2.5in) | |
1333 | @\@f[CONNECTION]@Index[CONNECTION]@\Represents an ongoing full duplex | |
1334 | @\@\connection to a central service. | |
1335 | ||
1336 | @\@f[CONN_STATUS]@Index[CONN_STATUS]@\a returned value indicating the | |
1337 | @\@\disposition of anattempted | |
1338 | @\@\library call. | |
1339 | ||
1340 | @\@f[OPERATION, OPERATION_DATA]@Index[OPERATION]@Index[OPERATION_DATA] | |
1341 | @\@\Represents an ongoing or completed | |
1342 | @\@\operation requested of | |
1343 | @\@\the server or transport system. | |
1344 | @\@\OPERATION is a handle | |
1345 | @\@\on OPERATION_DATA. | |
1346 | ||
1347 | @\@f[LIST_OF_OPERATIONS]@Index[LIST_OF_OPERATIONS] | |
1348 | @\@\A collection of OPERATIONs. | |
1349 | ||
1350 | @\@f[OP_STATUS]@Index[OP_STATUS]@\A return value describing the | |
1351 | @\@\progress of an asynchronous | |
1352 | @\@\operation. | |
1353 | @end(table) | |
1354 | ||
1355 | @section(Host and service names) | |
1356 | @Index(Host names) | |
1357 | @Index(Service names) | |
1358 | @Index(Naming hosts) | |
1359 | @Index(Naming services) | |
1360 | @Index(Naming communicating programs) | |
1361 | ||
1362 | In the current implementation, the address of a GDB program running on the | |
1363 | network has the form: | |
1364 | ||
1365 | @begin(example) | |
1366 | "hostname:servicename" | |
1367 | @end(example) | |
1368 | ||
1369 | where hostname is the internet name of the host on which the program | |
1370 | is running, and servicename is the name of the service as registered | |
1371 | in @f[/etc/services]@index[/etc/services]. Services should be of type | |
1372 | tcp. An alternate form of servicename is #portnumber, where | |
1373 | portnumber is the integer number of the Berkeley port to be used for | |
1374 | the service. Use of explicit port numbers is discouraged, except for | |
1375 | testing. Examples: "myhost:dbserver" or "yourhost:#1234". All | |
1376 | addresses are represented as null terminated strings in C. | |
1377 | ||
1378 | The form of GDB addresses may evolve over time. For example, host names | |
1379 | may disappear when better nameservers become available. | |
1380 | ||
1381 | @section(Routines for Use at Client) | |
1382 | ||
1383 | @begin(functionsection) | |
1384 | @begin(function) | |
1385 | CONNECTION | |
1386 | @f[start_server_connection](server_id, parms) | |
1387 | @index[start_server_connection] | |
1388 | string server_id; | |
1389 | string parms; | |
1390 | @end(function) | |
1391 | ||
1392 | Sets up a connection to a server process at the server site. server_id | |
1393 | identifies the service; its form is specified above. This routine | |
1394 | allocates a local socket and negotiates with the server to bind it to a | |
1395 | socket owned by the appropriate server process. The parms are made | |
1396 | available to the server. | |
1397 | ||
1398 | @begin(function) | |
1399 | CONNECTION | |
1400 | @f[start_peer_connection](peer_id) | |
1401 | @index[start_peer_connection] | |
1402 | string peer_id; | |
1403 | @end(function) | |
1404 | ||
1405 | Sets up a connection to a peer process, which may be at a remote site. | |
1406 | peer_id identifies the process to which the connection is to be made; its | |
1407 | form is specified above. This routine allocates a | |
1408 | local socket and negotiates to bind to a socket owned by the appropriate | |
1409 | peer process. Returns NULL if the connection could not be started. | |
1410 | Right now, there is no way to tell why the connection attempt failed. This | |
1411 | should be fixed in subsequent versions of the spec. | |
1412 | ||
1413 | @begin(function) | |
1414 | CONN_STATUS | |
1415 | @f[connection_status](connection) | |
1416 | @index[connection_status] | |
1417 | CONNECTION connection; | |
1418 | @end(function) | |
1419 | ||
1420 | Returns the status of the indicated connection. Possible return values are: | |
1421 | CONN_STOPPED (never started or severed by user), CON_UP (currentfly usable), | |
1422 | CON_STARTING (transient state on way up), CON_STOPPING(transient state on | |
1423 | way down--user is expected to check connection_errno and sever the connection.) | |
1424 | ||
1425 | @begin(function) | |
1426 | int | |
1427 | @f[connection_errno](connection) | |
1428 | @index[connection_errno] | |
1429 | CONNECTION connection; | |
1430 | @end(function) | |
1431 | ||
1432 | Returns the Unix errno which resulted in this connection being stopped. | |
1433 | While errno may be queried for any connection, it's value is meaningful | |
1434 | only for a connection in the CON_STOPPING state. | |
1435 | ||
1436 | @begin(function) | |
1437 | int | |
1438 | @f[connection_perror](connection, msg) | |
1439 | @index[connection_perror] | |
1440 | CONNECTION connection; | |
1441 | char *msg; | |
1442 | @end(function) | |
1443 | ||
1444 | Does the equivalent of the Unix perror library routine except (1) the | |
1445 | value of errno is that which caused this connection to stop and (2) | |
1446 | the error message is written to gdb_log, which may or may not be | |
1447 | stderr. This routine does nothing of connection is NULL or if | |
1448 | connection_status(connection) != CON_STOPPING. | |
1449 | ||
1450 | @begin(function) | |
1451 | CONNECTION | |
1452 | @f[sever_connection](connection) | |
1453 | @index[sever_connection] | |
1454 | CONNECTION connection; | |
1455 | @end(function) | |
1456 | ||
1457 | Applications should use this routine to terminate a connection. It may be | |
1458 | called on any active or stopping connection. The connection is terminated, | |
1459 | all pending operations are completed or (more likely) cancelled, and the | |
1460 | associated descriptor is released. This routine always returns NULL. It | |
1461 | is the applcation's responsibility to NULL its own connection variable, which | |
1462 | may conveniently be done with a construction of the form: | |
1463 | ||
1464 | @begin(example) | |
1465 | peer = sever_connection(peer); | |
1466 | @end(example) | |
1467 | ||
1468 | which has the effect of terminating the peer connection and safely nulling | |
1469 | the applications pointer. This is important because connection | |
1470 | descriptors are re-used when new connections are started. The old value | |
1471 | in a connection variable should NEVER be used after a sever. In particular, | |
1472 | the construction: | |
1473 | ||
1474 | @begin(example) | |
1475 | connection_status(severed_connection) | |
1476 | @end(example) | |
1477 | ||
1478 | is safe only when the application can insure that no new connections have | |
1479 | been started since the sever. | |
1480 | ||
1481 | Sever_connection is the inverse of start_peer_connection and | |
1482 | start_server_connection. It informs the foreign process that the client is | |
1483 | done with the connection, and releases all resources associated with the | |
1484 | connection. | |
1485 | @end(functionsection) | |
1486 | ||
1487 | @section(Routines for Use in Forking Servers) | |
1488 | @Index(Forking servers) | |
1489 | @Index(Servers, forking) | |
1490 | ||
1491 | @begin(functionsection) | |
1492 | @begin(function) | |
1493 | CONNECTION | |
1494 | @f[create_forking_server](servicename, validate-rtn) | |
1495 | @index[create_forking_server] | |
1496 | string servicename; | |
1497 | int *validate-rtn(); | |
1498 | @end(function) | |
1499 | ||
1500 | Turns the current process into a forking style server. The validate | |
1501 | routine, if supplied, is called before a connection is accepted to allow | |
1502 | the server to screen clients. (Interface to be documented later.) GDB | |
1503 | handles all management of connections, forking, child reaping, and the | |
1504 | like. No return is ever made in the parent, which remains under the | |
1505 | control of GDB forever. GDB will take care of terminating children | |
1506 | whenever the parent is killed. As new clients are received, GDB does the | |
1507 | necessary creation of connections and returns in the child processes. The | |
1508 | connection returned by this call is to be used in communicating with the | |
1509 | client. Because a true fork is done, global data may be inherited from the | |
1510 | master process. In addition, the global variable gdb_client_tuple is | |
1511 | initialized to contain four string fields named "server_id", "parms", | |
1512 | "host", and "user". | |
1513 | The first is the string name of the server as passed by the client, and the | |
1514 | second is the parms string supplied by the client. The last two are the | |
1515 | string names of the client host and user, as best GDB could determine them. | |
1516 | In some cases, GDB may supply "????" for either of these fields if | |
1517 | the true values cannot be determined. The child | |
1518 | may use the full facilities of GDB to communicate with its client, and when | |
1519 | communication is finished, the child should sever its connection (not | |
1520 | stricly required, but it's a good thing to do) and exit. The server will | |
1521 | appropriately reap the child process. Note that the servicename supplied | |
1522 | to this routine is NOT a full network address, since the host is implicitly | |
1523 | local. See service addressing discussion above. | |
1524 | ||
1525 | As an aid to debugging, the GDB_NOFORK@index[GDB_NOFORK] flag may be | |
1526 | set to prevent this routine from forking when a client arrives. See | |
1527 | @f[gdb_debug]@index[gdb_debug]. | |
1528 | @end(functionsection) | |
1529 | ||
1530 | @section(Routines for Use in Non-Forking Servers) | |
1531 | @begin(functionsection) | |
1532 | @begin(function) | |
1533 | int | |
1534 | @f[create_listening_connection](servicename) | |
1535 | @index[create_listening_connection] | |
1536 | string servicename; | |
1537 | @end(function) | |
1538 | ||
1539 | Creates a special 'listening' connection on which start_accepting_client | |
1540 | operations (see below) may be queued. Using these two facilities together, | |
1541 | a server may asynchronously wait for and acquire connections to new clients | |
1542 | while continuing to service existing clients. Servicename has the same | |
1543 | forms as for create_forking_server. | |
1544 | ||
1545 | @begin(function) | |
1546 | int | |
1547 | @f[start_accepting_client_connection](listencon, op, | |
1548 | &clientcon, &otherside | |
1549 | @index[start_accepting_client_connection] | |
1550 | &othersize, &client_tuple); | |
1551 | CONNECTION listencon; | |
1552 | OPERATION op; | |
1553 | CONNECTION clientcon; | |
1554 | struct sockaddr_in otherside; | |
1555 | int othersize; | |
1556 | TUPLE client_tuple; | |
1557 | @end(function) | |
1558 | ||
1559 | Begins the process of asynchronously acquiring a tentative connection from | |
1560 | a client. When this operation completes successfully, clientcon contains | |
1561 | the connection to the new client, and client_tuple contains the request tuple | |
1562 | (which includes the address requested and the client supplied parms). | |
1563 | The otherside and othersize fields are provided for those programmers who | |
1564 | need access to the Berkeley supplied address of the client. These are the | |
1565 | same as the values returned by a Berkeley 'accept' call. Most callers will | |
1566 | not need these, but it is required that appropriate parameters be supplied. | |
1567 | otherside may be a character array of length 100 (less will probably do) | |
1568 | and othersize should be an integer variable set to sizeof(otherside). The | |
1569 | actual size of the client address is returned, a la Berkeley accept. | |
1570 | ||
1571 | @begin(function) | |
1572 | int | |
1573 | @f[start_replying_to_client](op, con, disposition, newaddr, parms) | |
1574 | @index[start_replying_to_client] | |
1575 | OPERATION op; | |
1576 | CONNECTION con; | |
1577 | int disposition; | |
1578 | string newaddr; | |
1579 | string parms; | |
1580 | @end(function) | |
1581 | ||
1582 | The first thing a server must do after successful competion of a | |
1583 | start_accepting_client is to reply to the client, indicating whether its | |
1584 | request is being accepted. The reply is sent on the new client connection | |
1585 | using start_replying_to_client. Disposition takes one of three values: | |
1586 | GDB_ACCEPTED, GDB_REFUSED, or GDB_FORWARDED. In most cases, newaddr and | |
1587 | parms should be null strings (""). GDB_ACCEPTED completes the process of | |
1588 | creating the connection from client to server. Once the start_replying | |
1589 | operation is complete, the client connection is available for data | |
1590 | transmission. GDB_REFUSED indicates that the server declines to talk to | |
1591 | the client, and if desired, it may indicate a reason in the parms string. | |
1592 | The server should wait for completion of the start_replying_to_client, then | |
1593 | sever the client connection. GDB_FORWARDED is used to tell the client that | |
1594 | the service being requested has moved, and to suggest a new address for the | |
1595 | client to try. The suggested address should be supplied in newaddr in the | |
1596 | hostname:servicename form shown above. The 'start_server_connection' which | |
1597 | the client has done takes care of the forwarding request automatically and | |
1598 | transparently. | |
1599 | @end(functionsection) | |
1600 | ||
1601 | @section(Routines for Manipulating Operations) | |
1602 | ||
1603 | @begin(functionsection) | |
1604 | @begin(function) | |
1605 | OPERATION | |
1606 | @f[create_operation](); | |
1607 | @index[create_operation] | |
1608 | @end(function) | |
1609 | ||
1610 | Allocates an operation descriptor and returns a pointer to it. Note | |
1611 | that the type OPERATION is just a handle, and the system assumes that | |
1612 | operation data structures remain allocated for as long as they are | |
1613 | needed. Knowledgeable application programmers can allocate their own | |
1614 | structures of type OPERATION_DATA and use the macro OPERATION_FROM_DATA | |
1615 | to create the necessary OPERATIONS efficiently. create_operation is | |
1616 | appropriate where dynamic allocation is desired or for convenience in | |
1617 | simple applications. | |
1618 | ||
1619 | @begin(function) | |
1620 | int | |
1621 | @f[delete_operation](operation) | |
1622 | @index[delete_operation] | |
1623 | OPERATION operation; | |
1624 | @end(function) | |
1625 | ||
1626 | Releases space for the specified operation; | |
1627 | ||
1628 | @begin(function) | |
1629 | OPERATION | |
1630 | @f[OPERATION_FROM_DATA](op_data) | |
1631 | @index[OPERATION_FROM_DATA] | |
1632 | OPERATION_DATA op_data; | |
1633 | @end(function) | |
1634 | ||
1635 | Given the operation data, this macro returns the corresponding OPERATION | |
1636 | handle. | |
1637 | ||
1638 | @begin(function) | |
1639 | Bool | |
1640 | @f[OP_DONE](operation) | |
1641 | @index[OP_DONE] | |
1642 | OPERATION operation; | |
1643 | @end(function) | |
1644 | ||
1645 | True iff the operation is OP_COMPLETE or OP_CANCELLED. | |
1646 | ||
1647 | @begin(function) | |
1648 | int | |
1649 | @f[OP_TAG](operation) | |
1650 | @index[OP_TAG] | |
1651 | @end(function) | |
1652 | ||
1653 | Every operation initiated by a given process has a unique integer tag | |
1654 | which identifies it. This macro returns the tag for a given operation. | |
1655 | Tags are re-assigned each time the queue_op routine is called. | |
1656 | Applications programmers will seldom have need to query or manipulate the | |
1657 | tags directly; they are an internal mechanism used primarily to track | |
1658 | operations which are being cancelled prematurely. Applications | |
1659 | programmers may occasionally find them useful as a means of generating | |
1660 | operation identifiers which are guaranteed unique over the life of the | |
1661 | process. | |
1662 | ||
1663 | @begin(function) | |
1664 | OP_STATUS | |
1665 | @f[complete_operation](pending_operation) | |
1666 | @index[complete_operation] | |
1667 | OPERATION pending_operation; | |
1668 | @end(function) | |
1669 | ||
1670 | Waits unconditionally for completion of the specified operation. If | |
1671 | several operations are outstanding, then waiting for a given operation | |
1672 | implies a wait for all of its predecessors. There is a separate queue | |
1673 | of operations for each connection, so the term predecessor is defined | |
1674 | only with respect to a given connection. Operations pending on other | |
1675 | connections DO proceed while awaiting completion of the specified | |
1676 | operation. This means that when waiting for several operations to complete, | |
1677 | the calls to complete_operation may be done in any order without affecting | |
1678 | the performance of the system. | |
1679 | ||
1680 | @begin(function) | |
1681 | LIST_OF_OPERATIONS | |
1682 | @f[create_list_of_operations](n, op1, op2, ..... opn) | |
1683 | @index[create_list_of_operations] | |
1684 | int n; | |
1685 | OPERATION op1, op2 ... opn) | |
1686 | @end(function) | |
1687 | ||
1688 | Creates and returns a list containing the supplied operation | |
1689 | descriptors. This list may then be passed to the op_select routines. | |
1690 | ||
1691 | @begin(function) | |
1692 | void | |
1693 | @f[delete_list_of_operations](op_list) | |
1694 | @index[delete_list_of_operations] | |
1695 | LIST_OF_OPERATIONS op_list; | |
1696 | @end(function) | |
1697 | ||
1698 | Reclaims the space for the supplied list of operations. | |
1699 | ||
1700 | @begin(function) | |
1701 | int | |
1702 | @f[op_select_any](list_of_pending_operations, nfds, | |
1703 | @index[op_select_any] | |
1704 | &readfds, &writefds, | |
1705 | &exceptfds, timeout) | |
1706 | LIST_OF_OPERATIONS list_of_pending_operations; | |
1707 | int nfds; | |
1708 | fd_set readfds, writefds, exceptfds; | |
1709 | struct timeval *timeout; | |
1710 | @end(function) | |
1711 | ||
1712 | This operation has exactly the same semantics as the select system | |
1713 | call, but in addition, it allows pending OPERATIONs to | |
1714 | progress. This operation hangs in a select. If activity is discovered | |
1715 | on any of the sockets controlled by the GDB library, then the | |
1716 | corresponding input is read and appropriate processing is done. If any | |
1717 | of the listed pending_operations completes or terminates due to error, | |
1718 | op_select returns. op_select also returns immediately if any of the | |
1719 | supplied operations is already complete. | |
1720 | ||
1721 | If activity is detected on any of the file descriptors supplied by the | |
1722 | user, then a count and bit fields are returned just as for select. | |
1723 | (Activity on database sockets is never reflected in either count or | |
1724 | bitfields.) Timeout causes a return, as with select. Upon return, the | |
1725 | program must check for competion or termination of any of the listed | |
1726 | operations, for activity on the selected file descriptors, and for | |
1727 | timeouts, if requested, since any or all of these may be reported | |
1728 | together. | |
1729 | ||
1730 | Return values are (>0) same as for regular select, (0) timeout, (-1) only | |
1731 | completion of one of the specified operations was detected. | |
1732 | ||
1733 | @begin(function) | |
1734 | int | |
1735 | @f[op_select_all](list_of_pending_operations, nfds, | |
1736 | @index[op_select_all] | |
1737 | &readfds, &writefds, | |
1738 | &exceptfds, timeout) | |
1739 | LIST_OF_OPERATIONS list_of_pending_operations; | |
1740 | int nfds; | |
1741 | fd_set readfds, writefds, exceptfds; | |
1742 | struct timeval *timeout; | |
1743 | @end(function) | |
1744 | ||
1745 | Same as op_select_any, except that (-1) is returned only when ALL of the | |
1746 | specified operations in the list have completed. Values (>=0) are returned | |
1747 | for timeout or activity on FD's specified in the masks. | |
1748 | ||
1749 | @begin(function) | |
1750 | int | |
1751 | @f[reset_operation](operation) | |
1752 | @index[reset_operation] | |
1753 | OPERATION operation; | |
1754 | @end(function) | |
1755 | ||
1756 | Sets the state of an operation back to OP_NOT_STARTED. This is | |
1757 | particularly useful for operations in a list passed to op_select_any. | |
1758 | @Index(op_select_any) | |
1759 | Op_select_any drops through immediately if any operation in the list | |
1760 | is marked complete. Once the operation is reset, it may be left in | |
1761 | the list without detrimental effect. reset_operation cannot be used | |
1762 | on an operation which is queued or running. | |
1763 | ||
1764 | @begin(function) | |
1765 | OP_STATUS | |
1766 | @f[cancel_operation](operation) | |
1767 | @index[cancel_operation] | |
1768 | OPERATION operation; | |
1769 | @end(function) | |
1770 | ||
1771 | Attempts to prematurely terminate execution of the specified operation. If | |
1772 | the operation is queued, then it is removed from the queue of the | |
1773 | connection on which it resides. If it is at the head of the queue and | |
1774 | running, then an attempt is made to signal the other end of the connection | |
1775 | to terminate execution. If the operation has already completed, | |
1776 | successfully or otherwise, then CANCEL_OPERATION does nothing. In general, | |
1777 | the application cannot assume that the cancellation takes effect | |
1778 | immediately, or that it will always succeed. The status of the operation | |
1779 | must be checked to ascertain its true state, and if necessary, the | |
1780 | application must wait for the operation to complete or terminate | |
1781 | prematurely. This call always returns immediately. It does not wait to | |
1782 | see whether the operation was indeed terminated prematurely. There is no | |
1783 | guarantee of prompt termination for any particular operation, since some | |
1784 | may be uninterruptible. The intent is to make a best effort. Returned | |
1785 | status covers only errors in the cancel operation itself. The caller must | |
1786 | still use 'complete_ operation' or 'op_select' to check for completion or | |
1787 | successful cancellation of the operation. | |
1788 | ||
1789 | @begin(function) | |
1790 | int | |
1791 | @f[OP_STATUS](operation); | |
1792 | @index[OP_STATUS] | |
1793 | OPERATION operation; | |
1794 | @end(function) | |
1795 | ||
1796 | Returns a code describing the progress or completion of the operation. | |
1797 | Returned values are OP_RUNNING, OP_COMPLETE or OP_COULDNT_START. In the | |
1798 | case of OP_COMPLETE OP_CANCELLING, OP_CANCELLED, or OP_COULDNT_START, the | |
1799 | operation_result library routine may be used to get information about the | |
1800 | success or failure of the actual operation. Note that OP_COMPLETE applies | |
1801 | to either success or failure, it merely implies that no further processing | |
1802 | remains to be done on the requested operation. OP_CANCELLED implies that | |
1803 | the operation was indeed terminated prematurely by a cancellation request. | |
1804 | In this case, OP_RESULT is not valid. | |
1805 | ||
1806 | @begin(function) | |
1807 | int | |
1808 | @f[OP_RESULT](operation); | |
1809 | @index[OP_RESULT] | |
1810 | OPERATION operation; | |
1811 | @end(function) | |
1812 | ||
1813 | Returns detailed error information from the previous database or other | |
1814 | operation request. The possible result codes depend on the particular | |
1815 | operation being performed, and they are documented along with the | |
1816 | operations themselves. The operation result is available ONLY when | |
1817 | the operation is OP_COMPLETE. Attempts to get results at other times | |
1818 | may result in fatal errors. | |
1819 | @end(functionsection) | |
1820 | ||
1821 | @section(Creating new asynchronous operations) | |
1822 | ||
1823 | In addition to operations like start_sending_object, which are | |
1824 | supplied with GDB, it is possible for users to create their own. This | |
1825 | is a tricky business, because Unix lacks any notion of lightweight | |
1826 | process. Until proper instructions are added to the GDB Users' Guide, | |
1827 | the best way to learn is to look at the source code for existing | |
1828 | operations provided with GDB. | |
1829 | ||
1830 | The general idea is that @f[initialize_operation] is called to fill in | |
1831 | the operation descriptor with enough state to drive the operation, and | |
1832 | then @f[queue_operation] is used to queue the descriptor on the | |
1833 | appropriate half connection. When the operation reaches the head of | |
1834 | the queue, GDB automatically invokes the first routine of the | |
1835 | operation, which was specified during initialization. This routine | |
1836 | proceeds as far as it can, updates its own state in the operation | |
1837 | descriptor (and an operation specific argument appendage), and | |
1838 | designates a new routine to receive control when further progress can | |
1839 | be made. The following routines are among those used in creating new | |
1840 | operations: | |
1841 | ||
1842 | @begin(functionsection) | |
1843 | @begin(function) | |
1844 | int | |
1845 | @f[initialize_operation](operation, init_function, arg, | |
1846 | cancel_function) | |
1847 | @index[initialize_operation] | |
1848 | OPERATION operation; | |
1849 | int (*init_function)() | |
1850 | char *arg; | |
1851 | int (*cancel_function)() | |
1852 | @end(function) | |
1853 | ||
1854 | Initializes the supplied operation with pointers to the supplied | |
1855 | initialization function with the supplied argument. The initialization | |
1856 | routine will be called when and if the operation reaches the head of the | |
1857 | operation queue for some connection, and it will be supplied the argument | |
1858 | arg. The cancel function, if non-null, will be called with the supplied | |
1859 | argument if for any reason the operation is to be canceled. It can do | |
1860 | things like freeing the space for the argument or other associated cleanup. | |
1861 | If cancel_function is NULL, then no special processing is done during | |
1862 | cancellation. The operation is put into the state OP_NOT_STARTED. | |
1863 | ||
1864 | @begin(function) | |
1865 | OP_STATUS | |
1866 | @f[queue_operation](con, direction, operation) | |
1867 | @index[queue_operation] | |
1868 | CONNECTION con; | |
1869 | int direction;<= values are CON_INPUT | |
1870 | and CON_OUTPUT | |
1871 | OPERATION operation; | |
1872 | @end(function) | |
1873 | ||
1874 | Takes the supplied operation and queues it for execution on the specified | |
1875 | half connection, assigning a new unique tag for the operation. The | |
1876 | supplied operation must be in the state OP_NOT_STARTED (this may or may not | |
1877 | be checked.) If possible, execution actually begins, and in some cases, | |
1878 | execution may complete by the time queue_operation returns. Status returned | |
1879 | reflects the latest known state of the operation. Transmission on all | |
1880 | connections may progress as a result of this operation. If the connection | |
1881 | is not currently operating, then it is marked as severed. NOTE: queue | |
1882 | operation is used only by programmers creating their own asynchronous | |
1883 | services. It should NOT be called by USERS of asynchronous services. | |
1884 | @end(functionsection) | |
1885 | @chapter(Miscellaneous System Services) | |
1886 | @Index(Miscellaneous services) | |
1887 | @begin(functionsection) | |
1888 | @begin(function) | |
1889 | void | |
1890 | @f[gdb_debug](flag) | |
1891 | @index[gdb_debug] | |
1892 | int flag; | |
1893 | @end(function) | |
1894 | ||
1895 | Toggles the specified debugging flag. Flags currently supported are: | |
1896 | @begin(itemize) | |
1897 | @begin(multiple) | |
1898 | @end(multiple) | |
1899 | GDB_LOG@index[GDB_LOG flag] | |
1900 | ||
1901 | When set, this flag tells gdb to write a variety of debugging information on | |
1902 | the file gdb_log. By default, this file is set to @f[stderr]@index[stderr], | |
1903 | but users may put their own stream pointers in gdb_log. The debugging | |
1904 | information is very detailed. It is intended primarily for those with | |
1905 | detailed knowledge of GDB's inner workings. | |
1906 | @begin(multiple) | |
1907 | GDB_NOFORK@index[GDB_NOFORK flag] | |
1908 | ||
1909 | Tells GDB not to fork when a client arrives for a forking server. | |
1910 | When this is set, the server accepts only a single client, and terminates | |
1911 | when the client severs its connection. This is useful for debugging servers | |
1912 | with dbx@index[dbx] or other debuggers which are incapable of handling | |
1913 | forking programs. | |
1914 | @end(multiple) | |
1915 | @end(itemize) | |
1916 | Warning: the interface to this routine is likely to change in subsequent | |
1917 | releases of GDB. | |
1918 | ||
1919 | @end(functionsection) | |
1920 | ||
1921 | @Appendix(Revisions to this document) | |
1922 | ||
1923 | @begin(table) | |
1924 | @caption(Library Reference Manual Revisions) | |
1925 | @tabset(.75in, 2in) | |
1926 | @\5/26/86@\Base document created | |
1927 | ||
1928 | @\6/23/86@\Re-define database operations for consistency | |
1929 | @\@\with protocol.specification. | |
1930 | ||
1931 | @\7/10@\Add reset_operation | |
1932 | ||
1933 | @\7/18@\Added some notes in sever_connection on | |
1934 | @\@\questions relating to maintenenance of | |
1935 | @\@\an out of band control stream. | |
1936 | @\@\Also, added requirement to call gdb_init. | |
1937 | ||
1938 | @\7/25@\Considerations for re-queueing operations | |
1939 | @\@\Changed names on OP_STATUS, OP_RESULT | |
1940 | ||
1941 | @\8/27@\General cleanup to match current state | |
1942 | @\@\of implemented system | |
1943 | ||
1944 | @\9/2@\Correct documentation of string routines | |
1945 | @\@\and show requirement for stdio.h | |
1946 | ||
1947 | @\9/10@\Corrections to start_db_operation and | |
1948 | @\@\start_db_query | |
1949 | ||
1950 | @\9/17@\Added information on printing | |
1951 | ||
1952 | @\11/11@\Added gdb_debug and associated flags. | |
1953 | ||
1954 | @\11/19@\Added DB_STATUS and associated return codes. | |
1955 | @\@\Fixed parm list to db_query. | |
1956 | ||
1957 | @\12/31@\Added host and user fields to client tuple | |
1958 | ||
1959 | @\1/9/87@\Fixed return values on send/receive object | |
1960 | @end(table) |