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

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

Added more terminal control. Chgd some names.

File size: 8.6 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 PID_T MASTER-FILENO)</procedure>
83
84As per the C function {{forkpty(3)}}, creates a new pty, and returns the master
85fd {{MASTER-FILENO}} and process-id of the created process.
86
87The pseudo-tty name, {{WINSIZE}}, and {{TERMIOS}} as in {{open_pty}}.
88
89Unavailable with Windows.
90
91==== Window size
92
93<procedure>(alloc-winsize) => WINSIZE</procedure>
94
95Returns the pointer to a new C {{struct winsize}}.
96
97<procedure>(free-winsize WINSIZE)</procedure>
98
99Releases a C struct winsize.
100
101<procedure>(make-winsize [#:rows COUNT] [#:columns COUNT] [#:xpixels COUNT] [#:ypixels COUNT]) => WINSIZE</procedure>
102
103Returns the pointer to a new C {{struct winsize}}, initialized per supplied arguments.
104
105Sets a finalizer.
106
107Winsize has the following accessors:
108
109<procedure>(winsize-col WINSIZE) => INTEGER</procedure>
110<procedure>(winsize-col-set! WINSIZE INTEGER)</procedure>
111
112<procedure>(winsize-row WINSIZE) => INTEGER</procedure>
113<procedure>(winsize-row-set! WINSIZE INTEGER)</procedure>
114
115<procedure>(winsize-xpixel WINSIZE) => INTEGER</procedure>
116<procedure>(winsize-xpixel-set! WINSIZE INTEGER)</procedure>
117
118<procedure>(winsize-ypixel WINSIZE) => INTEGER</procedure>
119<procedure>(winsize-ypixel-set! WINSIZE INTEGER)</procedure>
120
121The domain of all {{INTEGER}} is {{unsigned short}}.
122
123Unavailable with Windows.
124
125==== Termios
126
127<procedure>(alloc-termios) => TERMIOS</procedure>
128
129Returns the pointer to a new C {{struct termios}}.
130
131<procedure>(free-termios TERMIOS)</procedure>
132
133Releases a C {{struct termios}}.
134
135<procedure>(make-termios [#:iflags TCFLAG_T] [#:oflags TCFLAG_T] [#:cflags TCFLAG_T] [#:lflags TCFLAG_T] [#:cc LIST | VECTOR | STRING]) => TERMIOS</procedure>
136
137Returns the pointer to a new C {{struct termios}}, initialized per supplied arguments.
138
139Sets a finalizer.
140
141Termios has the following accessors:
142
143<procedure>(termios-cc TERMIOS IDX) => CC_T</procedure>
144<procedure>(termios-cc-set! TERMIOS IDX CC_T)</procedure>
145
146<procedure>(termios-cflag TERMIOS) => TCFLAG_T</procedure>
147<procedure>(termios-cflag-set! TERMIOS TCFLAG_T)</procedure>
148
149<procedure>(termios-iflag TERMIOS) => TCFLAG_T</procedure>
150<procedure>(termios-iflag-set! TERMIOS TCFLAG_T)</procedure>
151
152<procedure>(termios-lflag TERMIOS) => TCFLAG_T</procedure>
153<procedure>(termios-lflag-set! TERMIOS TCFLAG_T)</procedure>
154
155<procedure>(termios-oflag TERMIOS) => TCFLAG_T</procedure>
156<procedure>(termios-oflag-set! TERMIOS TCFLAG_T)</procedure>
157
158Unavailable with Windows.
159
160===
161
162{{SPEED}}
163
164{{TERMIOS}} is a {{(c-pointer struct termios)}}.
165
166{{FILENO}}
167
168<procedure>(terminal-control-input-speed TERMIOS) => SPEED</procedure>
169<procedure>(terminal-control-output-speed TERMIOS) => SPEED</procedure>
170<procedure>(set-terminal-control-input-speed! TERMIOS SPEED)</procedure>
171<procedure>(set-terminal-control-output-speed! TERMIOS SPEED)</procedure>
172
173Get & set input & output speed elements of the {{TERMIOS}}, respectively.
174
175<procedure>(set-terminal-control-speed! TERMIOS SPEED)</procedure>
176
177Set both input & output speed elements of the {{TERMIOS}}.
178
179<procedure>(terminal-control-attributes FILENO [TERMIOS]) => TERMIOS</procedure>
180<procedure>(set-terminal-control-attributes! FILENO ACTION TERMIOS)</procedure>
181
182Get & set the {{TERMIOS}} elements.
183
184<procedure>(terminal-control-drain FILENO)</procedure>
185
186<procedure>(terminal-control-flow FILENO ACTION)</procedure>
187
188<procedure>(terminal-control-flush FILENO ACTION)</procedure>
189
190<procedure>(terminal-control-send-break FILENO DURATION)</procedure>
191
192<procedure>(terminal-control-make-raw TERMIOS)</procedure>
193
194==== Terminal Information
195
196<procedure>(terminal-type-device? FILENO) => BOOLEAN</procedure>
197
198Does the file descriptor {{FILENO}} refer to a valid terminal type device?
199
200The {{isatty(3)}} system call.
201
202<procedure>(terminal-device-name FILENO) => STRING</procedure>
203
204Returns the related device name for the file descriptor {{FILENO}}, or {{#f}}
205if not a tty device.
206
207The {{ttyname(3)}} system call.
208
209<procedure>(current-process-tty-number) => INTEGER</procedure>
210
211Returns the current process' control terminal number, or {{0}} if there isn't one.
212
213The {{ttyslot(3)}} system call.
214
215Unavailable with Windows.
216
217==== Stat object types
218
219The [[Unit posix]] declares constants for file modes, but the mode returned by
220{{file-stat}} also includes higher-order bits for the type of object. See the
221manpage for {{stat(2)}} for details.
222
223<constant>stat/ifmt</constant>
224<constant>stat/ififo</constant>
225<constant>stat/ifchr</constant>
226<constant>stat/ifdir</constant>
227<constant>stat/ifblk</constant>
228<constant>stat/ifreg</constant>
229<constant>stat/iflnk</constant>
230<constant>stat/ifsock</constant>
231
232Unavailable with Windows.
233
234==== File metadata
235
236<procedure>(change-link-mode FILENAME MODE)</procedure>
237
238As per {{change-file-mode}} in [[Unit posix]], but if used on a symlink,
239operates upon the link itself rather than on the object linked to.
240
241<procedure>(change-link-owner FILENAME UID GID)</procedure>
242
243As per {{change-file-owner}} in [[Unit posix]], but if used on a symlink,
244operates upon the link itself rather than on the object linked to.
245
246<procedure>(create-special-file FILENAME MODE DEVICE-NUMBER)</procedure>
247
248Creates a special file using the {{mknod(2)}} system call.
249
250<procedure>(change-file-times FILENAME ATIME MTIME)</procedure>
251
252Sets the atime and mtime of a file using the {{utime(2)}} system call.
253
254Unavailable with Windows.
255
256== Examples
257
258
259== Notes
260
261
262== Bugs and Limitations
263
264
265== Author
266
267[[kon lovett|Kon Lovett]]
268[[alaric-blagrave-snellpym|Alaric Snell-Pym]]
269
270
271== License
272
273Copyright (C) 2006-2008 Kon Lovett.  All rights reserved.
274Copyright (C) 2009 Kon Lovett, Alaric Snell-Pym.  All rights reserved.
275
276Permission is hereby granted, free of charge, to any person obtaining a
277copy of this software and associated documentation files (the Software),
278to deal in the Software without restriction, including without limitation
279the rights to use, copy, modify, merge, publish, distribute, sublicense,
280and/or sell copies of the Software, and to permit persons to whom the
281Software is furnished to do so, subject to the following conditions:
282
283The above copyright notice and this permission notice shall be included
284in all copies or substantial portions of the Software.
285
286THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
287IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
288FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
289THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
290OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
291ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
292OTHER DEALINGS IN THE SOFTWARE.
293
294
295== Requirements
296
297
298== Version history
299
300; 1.0 :
Note: See TracBrowser for help on using the repository browser.