source: project/release/3/posix-extensions/trunk/posix-extensions.wiki @ 13129

Last change on this file since 13129 was 13129, checked in by Kon Lovett, 12 years ago

Added termios constants. Made sep err file.

File size: 14.3 KB
Line 
1[[tags: egg]]
2
3== posix-extensions
4
5[[toc:]]
6
7== Usage
8
9(require-extension posix-extensions)
10
11== Documentation
12
13=== File Descriptors
14
15<procedure>(replace-fileno NEW-FILENO KNOWN-FILENO)</procedure>
16
17Replaces the meaning of {{KNOWN-FILENO}} with {{NEW-FILENO}}.
18
19=== Scheduling Priority
20
21Processes are identified by two values, {{WHICH}} and {{WHO}}. The value of
22{{WHICH}} defines how {{WHO}} is interpreted.
23
24The {{WHICH}} values are:
25
26<constant>prio/process</constant>
27
28{{WHO}} is a process ID, or {{0}} to refer to the current process.
29
30<constant>prio/process-group</constant>
31
32{{WHO}} is a process group ID, or {{0}} to refer to the current process group.
33
34<constant>prio/user</constant>
35
36{{WHO}} is a user ID, or {{0}} to refer to the current user.
37
38MacOS X Specific:
39
40<constant>prio/darwin-thread</constant>
41
42{{WHO}} is {{0}} for the current thread.
43
44<procedure>(scheduling-priority WHICH WHO)</procedure>
45
46Returns the priority of {{WHO}} of kind {{WHICH}}.
47
48<procedure>(set-scheduling-priority! WHICH WHO PRIORITY)</procedure>
49
50Sets the priority of {{WHO}} of kind {{WHICH}} to {{PRIORITY}}, which must be
51an integer between {{-20}} and {{20}} inclusive.
52
53MacOS X Specific:
54
55<constant>prio/darwin-bg</constant>
56
57When {{WHICH}} is {{prio/darwin-thread}} then the {{PRIORITY}} must be
58{{0}} or {{prio/darwin-bg}}.
59
60Unavailable with Windows.
61
62=== Pseudo-TTYs
63
64<procedure>(login-tty FILENO)</procedure>
65
66As per the C function {{login_tty(3)}}, prepares the tty for use.
67
68{{FILENO}} is usually the slave-fileno of a pseudo-tty but can be an real open
69tty device.
70
71<procedure>(open-pseudo-tty [WINSIZE [TERMIOS]]) => (values MASTER-FILENO SLAVE-FILENO)</procedure>
72
73As per the C function {{openpty(3)}}, creates a new pty, and returns the master
74and slave fds {{MASTER-FILENO}} and {{SLAVE-FILENO}}.
75
76{{WINSIZE}} and {{TERMIOS}} are {{pointers}}, or {{#f}}, to the respective structures, see below.
77
78The pseudo-tty name must be retrieved using the {{terminal-device-name}}
79procedure. A non-null {{name}} argument of the {{openpty}} system call can
80result in buffer overflow.
81
82<procedure>(fork-pseudo-tty THUNK [WINSIZE [TERMIOS]]) => (values CHILD-PID MASTER-FILENO)</procedure>
83
84As per the C function {{forkpty(3)}}, creates a new pty, and returns the
85process-id {{CHILD-PID}} and master fd {{MASTER-FILENO}} of the child process
86to the parent process.
87
88{{THUNK}} is executed in the child process.
89
90The pseudo-tty name, {{WINSIZE}}, and {{TERMIOS}} as in {{open_pty}}.
91
92Unavailable with Windows.
93
94==== Window size
95
96<procedure>(alloc-winsize) => WINSIZE</procedure>
97
98Returns the pointer to a new C {{struct winsize}}.
99
100<procedure>(free-winsize WINSIZE)</procedure>
101
102Releases a C struct winsize.
103
104<procedure>(make-winsize [#:rows COUNT] [#:columns COUNT] [#:xpixels COUNT] [#:ypixels COUNT]) => WINSIZE</procedure>
105
106Returns the pointer to a new C {{struct winsize}}, initialized per supplied arguments.
107
108{{COUNT}} is an unsigned exact integer {{unsigned short}}.
109
110Sets a finalizer.
111
112Winsize has the following accessors:
113
114<procedure>(winsize-col WINSIZE) => COUNT</procedure>
115<procedure>(winsize-col-set! WINSIZE COUNT)</procedure>
116
117<procedure>(winsize-row WINSIZE) => COUNT</procedure>
118<procedure>(winsize-row-set! WINSIZE COUNT)</procedure>
119
120<procedure>(winsize-xpixel WINSIZE) => COUNT</procedure>
121<procedure>(winsize-xpixel-set! WINSIZE COUNT)</procedure>
122
123<procedure>(winsize-ypixel WINSIZE) => COUNT</procedure>
124<procedure>(winsize-ypixel-set! WINSIZE COUNT)</procedure>
125
126Unavailable with Windows.
127
128==== Termios
129
130The follow constants are as per the Unix General Terminal Interface.
131
132Input Flags (TCFLAG):
133
134<constant>termios/ignbrk</constant>
135<constant>termios/brkint</constant>
136<constant>termios/ignpar</constant>
137<constant>termios/parmrk</constant>
138<constant>termios/inpck</constant>
139<constant>termios/istrip</constant>
140<constant>termios/inlcr</constant>
141<constant>termios/igncr</constant>
142<constant>termios/icrnl</constant>
143<constant>termios/iuclc</constant>
144<constant>termios/ixon</constant>
145<constant>termios/ixoff</constant>
146<constant>termios/ixany</constant>
147<constant>termios/iutf8</constant>
148<constant>termios/imaxbel</constant>
149
150Output Flags (TCFLAG):
151
152<constant>termios/opost</constant>
153<constant>termios/olcuc</constant>
154<constant>termios/onlcr</constant>
155<constant>termios/ocrnl</constant>
156<constant>termios/onocr</constant>
157<constant>termios/onlret</constant>
158<constant>termios/ofill</constant>
159<constant>termios/nldly</constant>
160<constant>termios/nl0</constant>
161<constant>termios/nl1</constant>
162<constant>termios/nl2</constant>
163<constant>termios/nl3</constant>
164<constant>termios/tabdly</constant>
165<constant>termios/tab0</constant>
166<constant>termios/tab1</constant>
167<constant>termios/tab2</constant>
168<constant>termios/tab3</constant>
169<constant>termios/crdly</constant>
170<constant>termios/cr0</constant>
171<constant>termios/cr1</constant>
172<constant>termios/cr2</constant>
173<constant>termios/cr3</constant>
174<constant>termios/ffdly</constant>
175<constant>termios/ff0</constant>
176<constant>termios/ff1</constant>
177<constant>termios/bsdly</constant>
178<constant>termios/bs0</constant>
179<constant>termios/bs1</constant>
180<constant>termios/vtdly</constant>
181<constant>termios/vt0</constant>
182<constant>termios/vt1</constant>
183<constant>termios/ofdel</constant>
184<constant>termios/oxtabs</constant>
185<constant>termios/onoeot</constant>
186
187Control Flags (TCFLAG):
188
189<constant>termios/cbaud</constant>
190<constant>termios/cbaudx</constant>
191<constant>termios/cibaud</constant>
192<constant>termios/loblk</constant>
193<constant>termios/csize</constant>
194<constant>termios/cs5</constant>
195<constant>termios/cs6</constant>
196<constant>termios/cs7</constant>
197<constant>termios/cs8</constant>
198<constant>termios/cstopb</constant>
199<constant>termios/cread</constant>
200<constant>termios/parenb</constant>
201<constant>termios/parodd</constant>
202<constant>termios/hupcl</constant>
203<constant>termios/clocal</constant>
204<constant>termios/cignore</constant>
205<constant>termios/mdmbuf</constant>
206<constant>termios/crtscts</constant>
207<constant>termios/ccts_oflow</constant>
208<constant>termios/crts-oflow</constant>
209<constant>termios/cdtr-oflow</constant>
210<constant>termios/cdsr-oflow</constant>
211<constant>termios/ccar-oflow</constant>
212
213Local Flags (TCFLAG):
214
215<constant>termios/xcase</constant>
216<constant>termios/isig</constant>
217<constant>termios/icanon</constant>
218<constant>termios/echoe</constant>
219<constant>termios/echok</constant>
220<constant>termios/echo</constant>
221<constant>termios/echonl</constant>
222<constant>termios/iexten</constant>
223<constant>termios/tostop</constant>
224<constant>termios/noflsh</constant>
225<constant>termios/echoctl</constant>
226<constant>termios/echoke</constant>
227<constant>termios/echoprt</constant>
228<constant>termios/pendin</constant>
229<constant>termios/flusho</constant>
230<constant>termios/altwerase</constant>
231<constant>termios/nokerninfo</constant>
232<constant>termios/extproc</constant>
233
234Special Control Character Indicies:
235
236<constant>termios/vswitch</constant>
237<constant>termios/veof</constant>
238<constant>termios/veol</constant>
239<constant>termios/verase</constant>
240<constant>termios/vkill</constant>
241<constant>termios/vintr</constant>
242<constant>termios/vquit</constant>
243<constant>termios/vsusp</constant>
244<constant>termios/vstart</constant>
245<constant>termios/vstop</constant>
246<constant>termios/vmin</constant>
247<constant>termios/vtime</constant>
248<constant>termios/veol2</constant>
249<constant>termios/vwerase</constant>
250<constant>termios/vreprint</constant>
251<constant>termios/vdsusp</constant>
252<constant>termios/vlnext</constant>
253<constant>termios/vdiscard</constant>
254<constant>termios/vstatus</constant>
255<constant>termios/nccs</constant>
256
257Special Control Characters (CC):
258
259
260
261<procedure>(alloc-termios) => TERMIOS</procedure>
262
263Returns the pointer to a new C {{struct termios}}.
264
265<procedure>(free-termios TERMIOS)</procedure>
266
267Releases a C {{struct termios}}.
268
269<procedure>(make-termios [#:iflags TCFLAG|LIST] [#:oflags TCFLAG|LIST] [#:cflags TCFLAG|LIST] [#:lflags TCFLAG|LIST] [#:cc LIST|VECTOR|STRING]) => TERMIOS</procedure>
270
271Returns the pointer to a new C {{struct termios}}, initialized per supplied arguments.
272
273A flag argument of type {{LIST}} is element-by-element or'ed to produce a {{TCFLAG}}.
274
275A control-character argument of type {{SEQUENCE}} must have {{CC}} elements.
276Any sequence elements beyond {{termios/nccs}} are ignored.
277
278Sets a finalizer.
279
280Termios has the following accessors:
281
282<procedure>(termios-cc TERMIOS IDX) => CC_T</procedure>
283<procedure>(termios-cc-set! TERMIOS IDX CC_T)</procedure>
284
285<procedure>(termios-cflag TERMIOS) => TCFLAG</procedure>
286<procedure>(termios-cflag-set! TERMIOS TCFLAG)</procedure>
287
288<procedure>(termios-iflag TERMIOS) => TCFLAG</procedure>
289<procedure>(termios-iflag-set! TERMIOS TCFLAG)</procedure>
290
291<procedure>(termios-lflag TERMIOS) => TCFLAG</procedure>
292<procedure>(termios-lflag-set! TERMIOS TCFLAG)</procedure>
293
294<procedure>(termios-oflag TERMIOS) => TCFLAG</procedure>
295<procedure>(termios-oflag-set! TERMIOS TCFLAG)</procedure>
296
297Unavailable with Windows.
298
299=== Terminal Speed
300
301<constant>termctl-baud/0</constant>
302<constant>termctl-baud/50</constant>
303<constant>termctl-baud/75</constant>
304<constant>termctl-baud/110</constant>
305<constant>termctl-baud/134</constant>
306<constant>termctl-baud/150</constant>
307<constant>termctl-baud/200</constant>
308<constant>termctl-baud/300</constant>
309<constant>termctl-baud/600</constant>
310<constant>termctl-baud/1200</constant>
311<constant>termctl-baud/1800</constant>
312<constant>termctl-baud/2400</constant>
313<constant>termctl-baud/4800</constant>
314<constant>termctl-baud/7200</constant>
315<constant>termctl-baud/9600</constant>
316<constant>termctl-baud/14400</constant>
317<constant>termctl-baud/19200</constant>
318<constant>termctl-baud/28800</constant>
319<constant>termctl-baud/38400</constant>
320<constant>termctl-baud/57600</constant>
321<constant>termctl-baud/76800</constant>
322<constant>termctl-baud/115200</constant>
323<constant>termctl-baud/230400</constant>
324<constant>termctl-baud/460800</constant>
325
326<procedure>(terminal-control-input-speed TERMIOS) => SPEED</procedure>
327<procedure>(terminal-control-output-speed TERMIOS) => SPEED</procedure>
328<procedure>(set-terminal-control-input-speed! TERMIOS SPEED)</procedure>
329<procedure>(set-terminal-control-output-speed! TERMIOS SPEED)</procedure>
330
331Get & set input & output speed elements of the {{TERMIOS}}, respectively.
332
333<procedure>(set-terminal-control-speed! TERMIOS SPEED)</procedure>
334
335Set both input & output speed elements of the {{TERMIOS}}.
336
337=== Terminal Attributes
338
339<constant>termctl-action/now</constant>
340<constant>termctl-action/drain</constant>
341<constant>termctl-action/flush</constant>
342<constant>termctl-action/soft</constant>
343
344<procedure>(terminal-control-attributes FILENO [TERMIOS]) => TERMIOS</procedure>
345<procedure>(set-terminal-control-attributes! FILENO ACTION TERMIOS)</procedure>
346
347Get & set the {{TERMIOS}} elements.
348
349=== Terminal Flow
350
351<constant>termctl-flow/output-off</constant>
352<constant>termctl-flow/output-on</constant>
353<constant>termctl-flow/input-off</constant>
354<constant>termctl-flow/input-on</constant>
355
356<procedure>(terminal-control-flow FILENO ACTION)</procedure>
357
358=== Terminal Flush
359
360<constant>termctl-flush/input</constant>
361<constant>termctl-flush/output</constant>
362<constant>termctl-flush/input-output</constant>
363
364<procedure>(terminal-control-flush FILENO ACTION)</procedure>
365
366=== Terminal Miscellaneous
367
368<procedure>(terminal-control-drain FILENO)</procedure>
369
370<procedure>(terminal-control-send-break FILENO DURATION)</procedure>
371
372<procedure>(terminal-control-make-raw TERMIOS)</procedure>
373
374==== Terminal Information
375
376<procedure>(terminal-device?? FILENO) => BOOLEAN</procedure>
377
378Does the file descriptor {{FILENO}} refer to a valid terminal type device?
379
380The {{isatty(3)}} system call.
381
382<procedure>(terminal-device-name FILENO) => STRING</procedure>
383
384Returns the related device name for the file descriptor {{FILENO}}, or {{#f}}
385if not a tty device.
386
387The {{ttyname(3)}} system call.
388
389<procedure>(current-process-tty-number) => INTEGER</procedure>
390
391Returns the current process' control terminal number, or {{0}} if there isn't one.
392
393The {{ttyslot(3)}} system call.
394
395Unavailable with Windows.
396
397==== Stat object types
398
399The [[Unit posix]] declares constants for file modes, but the mode returned by
400{{file-stat}} also includes higher-order bits for the type of object. See the
401manpage for {{stat(2)}} for details.
402
403<constant>stat/ifmt</constant>
404<constant>stat/ififo</constant>
405<constant>stat/ifchr</constant>
406<constant>stat/ifdir</constant>
407<constant>stat/ifblk</constant>
408<constant>stat/ifreg</constant>
409<constant>stat/iflnk</constant>
410<constant>stat/ifsock</constant>
411
412Unavailable with Windows.
413
414==== File metadata
415
416<procedure>(change-link-mode FILENAME MODE)</procedure>
417
418As per {{change-file-mode}} in [[Unit posix]], but if used on a symlink,
419operates upon the link itself rather than on the object linked to.
420
421<procedure>(change-link-owner FILENAME UID GID)</procedure>
422
423As per {{change-file-owner}} in [[Unit posix]], but if used on a symlink,
424operates upon the link itself rather than on the object linked to.
425
426<procedure>(create-special-file FILENAME MODE DEVICE-NUMBER)</procedure>
427
428Creates a special file using the {{mknod(2)}} system call.
429
430<procedure>(change-file-times FILENAME ATIME MTIME)</procedure>
431
432Sets the atime and mtime of a file using the {{utime(2)}} system call.
433
434Unavailable with Windows.
435
436== Examples
437
438
439== Notes
440
441
442== Bugs and Limitations
443
444
445== Author
446
447[[kon lovett|Kon Lovett]]
448[[alaric-blagrave-snellpym|Alaric Snell-Pym]]
449
450
451== License
452
453Copyright (C) 2006-2008 Kon Lovett.  All rights reserved.
454Copyright (C) 2009 Kon Lovett, Alaric Snell-Pym.  All rights reserved.
455
456Permission is hereby granted, free of charge, to any person obtaining a
457copy of this software and associated documentation files (the Software),
458to deal in the Software without restriction, including without limitation
459the rights to use, copy, modify, merge, publish, distribute, sublicense,
460and/or sell copies of the Software, and to permit persons to whom the
461Software is furnished to do so, subject to the following conditions:
462
463The above copyright notice and this permission notice shall be included
464in all copies or substantial portions of the Software.
465
466THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
467IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
468FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
469THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
470OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
471ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
472OTHER DEALINGS IN THE SOFTWARE.
473
474
475== Requirements
476
477
478== Version history
479
480; 1.0 :
Note: See TracBrowser for help on using the repository browser.