source: project/chicken/trunk/manual/Unit posix @ 10513

Last change on this file since 10513 was 10513, checked in by Ivan Raikov, 11 years ago

Version increased to 3.1.6

File size: 39.1 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit posix
5
6This unit provides services as used on many UNIX-like systems.  Note that
7the following definitions are not all available on non-UNIX systems like
8Windows. See below for Windows specific notes.
9
10This unit uses the {{regex}}, {{scheduler}}, {{extras}} and {{utils}} units.
11
12All errors related to failing file-operations will signal a condition
13of kind {{(exn i/o file)}}.
14
15
16=== Constants
17
18==== File-control Commands
19
20===== fcntl/dupfd
21===== fcntl/getfd
22===== fcntl/setfd
23===== fcntl/getfl
24===== fcntl/setfl
25
26==== Standard I/O file-descriptors
27
28===== fileno/stdin
29===== fileno/stdout
30===== fileno/stderr
31
32==== Open flags
33
34===== open/rdonly
35===== open/wronly
36===== open/rdwr
37===== open/read
38===== open/write
39===== open/creat
40===== open/append
41===== open/excl
42===== open/noctty
43===== open/nonblock
44===== open/trunc
45===== open/sync
46===== open/fsync
47===== open/binary
48===== open/text
49
50==== Permission bits
51
52===== perm/irusr
53===== perm/iwusr
54===== perm/ixusr
55===== perm/irgrp
56===== perm/iwgrp
57===== perm/ixgrp
58===== perm/iroth
59===== perm/iwoth
60===== perm/ixoth
61===== perm/irwxu
62===== perm/irwxg
63===== perm/irwxo
64===== perm/isvtx
65===== perm/isuid
66===== perm/isgid
67
68
69=== Directories
70
71==== change-directory
72
73 [procedure] (change-directory NAME)
74
75Changes the current working directory to {{NAME}}.
76
77==== current-directory
78
79 [procedure] (current-directory [DIR])
80
81Returns the name of the current working directory. If the optional argument {{DIR}} is given,
82then {{(current-directory DIR)}} is equivalent to {{(change-directory DIR)}}.
83
84==== create-directory
85
86 [procedure] (create-directory NAME #!optional PARENTS?)
87
88Creates a directory with the pathname {{NAME}}.  If the {{PARENTS?}} argument
89is given and not false, any nonextant parent directories are also created.
90
91==== delete-directory
92
93 [procedure] (delete-directory NAME)
94
95Deletes the directory with the pathname {{NAME}}. The directory has
96to be empty.
97
98==== directory
99
100 [procedure] (directory [PATHNAME [SHOW-DOTFILES?]])
101
102Returns a list with all files that are contained in the directory with the name {{PATHNAME}}
103(which defaults to the value of {{(current-directory)}}).
104Files beginning with {{.}} are included only if {{SHOW-DOTFILES?}} is given and not {{#f}}.
105
106==== directory?
107
108 [procedure] (directory? NAME)
109
110Returns {{#t}} if there exists a file with the name {{NAME}}
111and if that file is a directory, or {{#f}} otherwise.
112
113==== glob
114
115 [procedure] (glob PATTERN1 ...)
116
117Returns a list of the pathnames of all existing files matching {{PATTERN1 ...}}, which should be strings containing the usual file-patterns (with {{*}} matching zero or more characters and {{?}} matching zero or one character).  Bug: wildcard characters are only recognized in the rightmost portion of the pattern.
118
119==== canonical-path
120
121 [procedure] (canonical-path NAME)
122
123Returns a canonical path for {{NAME}}, which should be a string
124containing a path-or-filename.  The string returned by
125{{canonical-path}} is OS dependent; it may be quoted and used in
126a shell on the calling machine. (Quoting is suggested as shell
127special characters, including space, are not escaped.)  However,
128all path separators and prefixes are handled in an OS independent
129fashion.  Any appearance of {{/}} below imply {{\\}} is also handled.
130
131The prefix for {{NAME}} determines what path to prepend.  If {{NAME}}
132begins with a {{"~/"}}, this prefix is stripped and the user's
133home directory is added.  If beginning with {{/}} or a DRIVE-LETTER:\\
134combination, no additional path is added.  Otherwise, the current
135directory and separator are added.  All relative path elements and
136duplicate separators are processed and removed.  If {{NAME}} ends with
137a {{/}} or is empty, the appropriate slash is appended to the tail.
138
139No directories or files are actually tested for existence; this
140procedure only canonicalises path syntax.
141
142==== set-root-directory!
143
144 [procedure] (set-root-directory! STRING)
145
146Sets the root directory for the current process to the path given in {{STRING}}
147(using the {{chroot}} function).
148If the current process has no root permissions, the operation will fail.
149
150
151=== Pipes
152
153==== call-with-input-pipe
154==== call-with-output-pipe
155
156 [procedure] (call-with-input-pipe CMDLINE PROC [MODE])
157 [procedure] (call-with-output-pipe CMDLINE PROC [MODE])
158
159Call {{PROC}} with a single argument: a input- or output port
160for a pipe connected to the subprocess named in {{CMDLINE}}. If
161{{PROC}} returns normally, the pipe is closed and any result values
162are returned.
163
164==== close-input-pipe
165==== close-output-pipe
166
167 [procedure] (close-input-pipe PORT)
168 [procedure] (close-output-pipe PORT)
169
170Closes the pipe given in {{PORT}} and waits until the connected
171subprocess finishes. The exit-status code of the invoked process
172is returned.
173
174==== create-pipe
175
176 [procedure] (create-pipe)
177
178The fundamental pipe-creation operator. Calls the C function
179{{pipe()}} and returns 2 values: the file-descriptors of the input-
180and output-ends of the pipe.
181
182==== open-input-pipe
183
184 [procedure] (open-input-pipe CMDLINE [MODE])
185
186Spawns a subprocess with the command-line string {{CMDLINE}} and
187returns a port, from which the output of the process can be read. If
188{{MODE}} is specified, it should be the keyword {{#:text}}
189(the default) or {{#:binary}}.
190
191==== open-output-pipe
192
193 [procedure] (open-output-pipe CMDLINE [MODE])
194
195Spawns a subprocess with the command-line string {{CMDLINE}} and
196returns a port. Anything written to that port is treated as the input
197for the process.  If {{MODE}} is specified, it should be the keyword
198{{#:text}} (the default) or {{#:binary}}.
199
200==== pipe/buf
201This variable contains the maximal number of bytes that can be written
202atomically into a pipe or FIFO.
203
204==== with-input-from-pipe
205==== with-output-to-pipe
206
207 [procedure] (with-input-from-pipe CMDLINE THUNK [MODE])
208 [procedure] (with-output-to-pipe CMDLINE THUNK [MODE])
209
210Temporarily set the value of
211{{current-input-port/current-output-port}} to a port for a
212pipe connected to the subprocess named in {{CMDLINE}} and call
213the procedure {{THUNK}} with no arguments. After {{THUNK}}
214returns normally the pipe is closed and the standard input-/output port
215is restored to its previous value and any result values are returned.
216
217<enscript highlight=scheme>
218(with-output-to-pipe
219  "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"
220  (lambda ()
221    (print #<<EOF
222 %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@xx.xxxxxx.xx.xx>
223 /C/neg/d/mul/R/rlineto/E/exp/H{{cvx def}repeat}def/T/dup/g/gt/r/roll/J/ifelse 8
224 H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
225 X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
226 F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
227 Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
228 ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
229 V1c&j2AYdjmMdjjd!o&1r!M){( )T 0 4 3 r put T(/)g{T(9)g{cvn}{cvi}J}{($)g[]J}J
230 cvx}forall/moveto/p/floor/w/div/S/add 29 H[{[{]setgray fill}for Y}for showpage
231 EOF
232 ) ) )
233</enscript>
234
235
236=== Fifos
237
238==== create-fifo
239
240 [procedure] (create-fifo FILENAME [MODE])
241
242Creates a FIFO with the name {{FILENAME}} and the permission bits
243{{MODE}}, which defaults to
244
245<enscript highlight=scheme>
246 [procedure] (+ perm/irwxu perm/irwxg perm/irwxo)
247</enscript>
248
249==== fifo?
250
251 [procedure] (fifo? FILENAME)
252
253Returns {{#t}} if the file with the name {{FILENAME}} names
254a FIFO.
255
256
257=== File descriptors and low-level I/O
258
259==== duplicate-fileno
260
261 [procedure] (duplicate-fileno OLD [NEW])
262
263If {{NEW}} is given, then the file-descriptor {{NEW}} is opened
264to access the file with the file-descriptor {{OLD}}. Otherwise a
265fresh file-descriptor accessing the same file as {{OLD}} is returned.
266
267==== file-close
268
269 [procedure] (file-close FILENO)
270
271Closes the input/output file with the file-descriptor {{FILENO}}.
272
273==== file-open
274
275 [procedure] (file-open FILENAME FLAGS [MODE])
276
277Opens the file specified with the string {{FILENAME}} and open-flags
278{{FLAGS}} using the C function {{open()}}. On success a
279file-descriptor for the opened file is returned.  {{FLAGS}}
280should be a bitmask containing one or more of the {{open/...}}
281values '''or'''ed together using {{bitwise-ior}} (or simply added
282together).  The optional {{MODE}} should be a bitmask composed of one
283or more permission values like {{perm/irusr}} and is only relevant
284when a new file is created. The default mode is
285{{perm/irwxu | perm/irgrp | perm/iroth}}.
286
287==== file-mkstemp
288
289 [procedure] (file-mkstemp TEMPLATE-FILENAME)
290
291Create a file based on the given {{TEMPLATE-FILENAME}}, in which
292the six last characters must be ''XXXXXX''.  These will be replaced
293with a string that makes the filename unique.  The file descriptor of
294the created file and the generated filename is returned.  See the
295{{mkstemp(3)}} manual page for details on how this function
296works.  The template string given is not modified.
297
298Example usage:
299
300<enscript highlight=scheme>
301 (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
302  (let ((temp-port (open-output-file* fd)))
303    (format temp-port "This file is ~A.~%" temp-path)
304    (close-output-port temp-port)))
305</enscript>
306
307==== file-read
308
309 [procedure] (file-read FILENO SIZE [BUFFER])
310
311Reads {{SIZE}} bytes from the file with the file-descriptor
312{{FILENO}}.  If a string or bytevector is passed in the optional
313argument {{BUFFER}}, then this string will be destructively modified
314to contain the read data. This procedure returns a list with two values:
315the buffer containing the data and the number of bytes read.
316
317==== file-select
318
319 [procedure] (file-select READFDLIST WRITEFDLIST [TIMEOUT])
320
321Waits until any of the file-descriptors given in the lists
322{{READFDLIST}} and {{WRITEFDLIST}} is ready for input or
323output, respectively. If the optional argument {{TIMEOUT}} is
324given and not false, then it should specify the number of seconds after
325which the wait is to be aborted (the value may be a floating point
326number). This procedure returns two values:
327the lists of file-descriptors ready for input and output, respectively.
328{{READFDLIST}} and '''WRITEFDLIST''' may also by file-descriptors
329instead of lists.  In this case the returned values are booleans
330indicating whether input/output is ready by {{#t}} or {{#f}}
331otherwise.  You can also pass {{#f}} as {{READFDLIST}} or
332{{WRITEFDLIST}} argument, which is equivalent to {{()}}.
333
334==== file-write
335
336 [procedure] (file-write FILENO BUFFER [SIZE])
337
338Writes the contents of the string or bytevector {{BUFFER}} into
339the file with the file-descriptor {{FILENO}}. If the optional
340argument {{SIZE}} is given, then only the specified number of bytes
341are written.
342
343==== file-control
344
345 [procedure] (file-control FILENO COMMAND [ARGUMENT])
346
347Performs the fcntl operation {{COMMAND}} with the given
348{{FILENO}} and optional {{ARGUMENT}}. The return value is
349meaningful depending on the {{COMMAND}}.
350
351==== open-input-file*
352==== open-output-file*
353
354 [procedure] (open-input-file* FILENO [OPENMODE])
355 [procedure] (open-output-file* FILENO [OPENMODE])
356
357Opens file for the file-descriptor {{FILENO}} for input or output
358and returns a port.  {{FILENO}} should be a positive exact integer.
359{{OPENMODE}} specifies an additional mode for opening the file
360(currently only the keyword {{#:append}} is supported, which opens
361an output-file for appending).
362
363==== port->fileno
364
365 [procedure] (port->fileno PORT)
366
367If {{PORT}} is a file- or tcp-port, then a file-descriptor is returned for
368this port. Otherwise an error is signaled.
369
370
371=== Retrieving file attributes
372
373==== file-access-time
374==== file-change-time
375==== file-modification-time
376
377 [procedure] (file-access-time FILE)
378 [procedure] (file-change-time FILE)
379 [procedure] (file-modification-time FILE)
380
381Returns time (in seconds) of the last access, modification or change of {{FILE}}. {{FILE}}
382may be a filename or a file-descriptor. If the file does not exist,
383an error is signaled.
384
385==== file-stat
386
387 [procedure] (file-stat FILE [LINK])
388
389Returns a 13-element vector with the following contents: inode-number,
390mode (as with {{file-permissions}}), number of hard links, uid of
391owner (as with {{file-owner}}), gid of owner, size (as with
392{{file-size}}) and access-, change- and modification-time (as with
393{{file-access-time}}, {{file-change-time}} and
394{{file-modification-time}}, device id, device type (for special file
395inode, blocksize and blocks allocated.  On Windows systems the last 4
396values are undefined.  If the optional argument {{LINK}} is given and
397not {{#f}}, then the file-statistics vector will be resolved for
398symbolic links (otherwise symbolic links are not resolved).
399Note that for very large files, the {{file-size}} value may be an
400inexact integer.
401
402==== file-position
403
404 [procedure] (file-position FILE)
405
406Returns the current file position of {{FILE}}, which should be a
407port or a file-descriptor.
408
409==== file-size
410
411 [procedure] (file-size FILENAME)
412
413Returns the size of the file designated by {{FILE}}.  {{FILE}}
414may be a filename or a file-descriptor.  If the file does not exist,
415an error is signaled. Note that for very large files, {{file-size}} may
416return an inexact integer.
417
418==== regular-file?
419
420 [procedure] (regular-file? FILENAME)
421
422Returns true, if {{FILENAME}} names a regular file (not a directory or symbolic link).
423
424==== file-owner
425
426 [procedure] (file-owner FILE)
427
428Returns the user-id of {{FILE}}.  {{FILE}} may be a filename
429or a file-descriptor.
430
431==== file-permissions
432
433 [procedure] (file-permissions FILE)
434
435Returns the permission bits for {{FILE}}. You can test this value
436by performing bitwise operations on the result and the {{perm/...}}
437values.  {{FILE}} may be a filename or a file-descriptor.
438
439==== file-read-access?
440==== file-write-access?
441==== file-execute-access?
442
443 [procedure] (file-read-access? FILENAME)
444 [procedure] (file-write-access? FILENAME)
445 [procedure] (file-execute-access? FILENAME)
446
447These procedures return {{#t}} if the current user has read,
448write or execute permissions on the file named {{FILENAME}}.
449
450
451==== stat-regular?
452==== stat-directory?
453==== stat-char-device?
454==== stat-block-device?
455==== stat-fifo?
456==== stat-symlink?
457==== stat-socket?
458
459 [procedure] (stat-regular? FILENAME)
460 [procedure] (stat-directory? FILENAME)
461 [procedure] (stat-char-device? FILENAME)
462 [procedure] (stat-block-device? FILENAME)
463 [procedure] (stat-fifo? FILENAME)
464 [procedure] (stat-symlink? FILENAME)
465 [procedure] (stat-socket? FILENAME)
466
467These procedures return {{#t}} if the {{FILENAME}} given is of the
468appropriate type.
469
470
471=== Changing file attributes
472
473==== file-truncate
474
475 [procedure] (file-truncate FILE OFFSET)
476
477Truncates the file {{FILE}} to the length {{OFFSET}},
478which should be an integer. If the file-size is smaller or equal to
479{{OFFSET}} then nothing is done.  {{FILE}} should be a filename
480or a file-descriptor.
481
482==== set-file-position!
483
484 [procedure] (set-file-position! FILE POSITION [WHENCE])
485 [procedure] (set! (file-position FILE) POSITION)
486
487Sets the current read/write position of {{FILE}} to
488{{POSITION}}, which should be an exact integer. {{FILE}}
489should be a port or a file-descriptor.  {{WHENCE}} specifies
490how the position is to interpreted and should be one of the values
491{{seek/set, seek/cur}} and {{seek/end}}. It defaults to
492{{seek/set}}.
493
494Exceptions: {{(exn bounds)}}, {{(exn i/o file)}}
495
496==== change-file-mode
497
498 [procedure] (change-file-mode FILENAME MODE)
499
500Changes the current file mode of the file named {{FILENAME}}
501to {{MODE}} using the {{chmod()}} system call.  The
502{{perm/...}} variables contain the various permission bits and can
503be combinded with the {{bitwise-ior}} procedure.
504
505==== change-file-owner
506
507 [procedure] (change-file-owner FILENAME UID GID)
508
509Changes the owner information of the file named {{FILENAME}} to
510the user- and group-ids {{UID}} and {{GID}} (which should be
511exact integers) using the {{chown()}} system call.
512
513
514=== Processes
515
516==== current-process-id
517
518 [procedure] (current-process-id)
519
520Returns the process ID of the current process.
521
522==== parent-process-id
523
524 [procedure] (parent-process-id)
525
526Returns the process ID of the parent of the current process.
527
528==== process-group-id
529
530 [procedure] (process-group-id PID)
531
532Returns the process group ID of the process specified by {{PID}}.
533
534==== process-execute
535
536 [procedure] (process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST]])
537
538Creates a new child process and replaces the running process with it
539using the C library function {{execvp(3)}}. If the optional argument
540{{ARGUMENT-LIST}} is given, then it should contain a list of strings which
541are passed as arguments to the subprocess. If the optional argument
542{{ENVIRONMENT-LIST}} is supplied, then the library function {{execve(2)}}
543is used, and the environment passed in {{ENVIRONMENT-LIST}} (which should
544be of the form {{("<NAME>=<VALUE>" ...)}} is given
545to the invoked process. Note that {{execvp(3)}} respects the current setting
546of the {{PATH}} environment variable while {{execve(3)}} does not.
547
548==== process-fork
549
550 [procedure] (process-fork [THUNK])
551
552Creates a new child process with the UNIX system call
553{{fork()}}. Returns either the PID of the child process or 0. If
554{{THUNK}} is given, then the child process calls it as a procedure
555with no arguments and terminates.
556
557==== process-run
558
559 [procedure] (process-run COMMANDLINE])
560 [procedure] (process-run COMMAND ARGUMENT-LIST)
561
562Creates a new child process. The PID of the new process is returned.
563
564* The single parameter version passes the {{COMMANDLINE}} to the system shell, so usual
565argument expansion can take place.
566* The multiple parameter version directly invokes the {{COMMAND}} with the {{ARGUMENT-LIST}}.
567
568==== process-signal
569
570 [procedure] (process-signal PID [SIGNAL])
571
572Sends {{SIGNAL}} to the process with the id {{PID}} using the
573UNIX system call {{kill()}}. {{SIGNAL}} defaults to the value
574of the variable {{signal/term}}.
575
576==== process-wait
577
578 [procedure] (process-wait [PID [NOHANG]])
579
580Suspends the current process until the child process with
581the id {{PID}} has terminated using the UNIX system call
582{{waitpid()}}. If {{PID}} is not given, then this procedure
583waits for any child process. If {{NOHANG}} is given and not
584{{#f}} then the current process is not suspended.  This procedure
585returns three values:
586
587* {{PID}} or 0, if {{NOHANG}} is true and the child process has not terminated yet.
588* {{#t}} if the process exited normally or {{#f}} otherwise.
589* either the exit status, if the process terminated normally or the signal number that terminated/stopped the process.
590
591==== process
592
593 [procedure] (process COMMANDLINE)
594 [procedure] (process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])
595
596Creates a subprocess and returns three values: an input port from
597which data written by the sub-process can be read, an output port from
598which any data written to will be received as input in the sub-process
599and the process-id of the started sub-process. Blocking reads and writes
600to or from the ports returned by {{process}} only block the current
601thread, not other threads executing concurrently.
602
603* The single parameter version passes the string {{COMMANDLINE}} to the host-system's shell that
604is invoked as a subprocess.
605* The multiple parameter version directly invokes the {{COMMAND}} as a subprocess. The {{ARGUMENT-LIST}}
606is directly passed, as is {{ENVIRONMENT-LIST}}.
607
608Not using the shell may be preferrable for security reasons.
609
610==== process*
611
612 [procedure] (process* COMMANDLINE)
613 [procedure] (process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])
614
615Like {{process}} but returns 4 values: an input port from
616which data written by the sub-process can be read, an output port from
617which any data written to will be received as input in the sub-process,
618the process-id of the started sub-process, and an input port from
619which data written by the sub-process to {{stderr}} can be read.
620
621==== sleep
622
623 [procedure] (sleep SECONDS)
624
625Puts the process to sleep for {{SECONDS}}. Returns either 0 if
626the time has completely elapsed, or the number of remaining seconds,
627if a signal occurred.
628
629==== create-session
630
631 [procedure] (create-session)
632
633Creates a new session if the calling process is not a process group leader and returns
634the session ID.
635
636
637=== Hard and symbolic links
638
639==== symbolic-link?
640
641 [procedure] (symbolic-link? FILENAME)
642
643Returns true, if {{FILENAME}} names a symbolic link.
644
645==== create-symbolic-link
646
647 [procedure] (create-symbolic-link OLDNAME NEWNAME)
648
649Creates a symbolic link with the filename {{NEWNAME}} that points
650to the file named {{OLDNAME}}.
651
652==== read-symbolic-link
653
654 [procedure] (read-symbolic-link FILENAME)
655
656Returns the filename to which the symbolic link {{FILENAME}} points.
657
658==== file-link
659
660 [procedure] (file-link OLDNAME NEWNAME)
661
662Creates a hard link from {{OLDNAME}} to {{NEWNAME}} (both strings).
663
664
665=== Retrieving user & group information
666
667==== current-user-id
668
669 [procedure] (current-user-id)
670 [setter] (set! (current-user-id) UID)
671
672Get or set the real user-id of the current process.
673
674==== current-effective-user-id
675
676 [procedure] (current-effective-user-id)
677 [setter] (set! (current-effective-user-id) UID)
678
679Get or set the effective user-id of the current process.
680
681==== user-information
682
683 [procedure] (user-information USER [AS-VECTOR])
684
685If {{USER}} specifes a valid username (as a string) or user ID, then the user
686database is consulted and a list of 7 values are returned: the user-name, the
687encrypted password, the user ID, the group ID, a user-specific string, the home
688directory and the default shell. When {{AS-VECTOR}} is {{#t}} a vector of 7
689elements is returned instead of a list. If no user with this name or id then
690{{#f}} is returned.
691
692==== current-group-id
693
694 [procedure] (current-group-id)
695 [setter] (set! (current-group-id) GID)
696
697Get or set the real group-id of the current process.
698
699==== current-effective-group-id
700
701 [procedure] (current-effective-group-id)
702 [setter] (set! (current-effective-group-id) GID)
703
704Get or set the effective group-id of the current process.
705ID can be found, then {{#f}} is returned.
706
707==== group-information
708
709 [procedure] (group-information GROUP)
710
711If {{GROUP}} specifies a valid group-name or group-id, then this
712procedure returns a list of four values: the group-name, the encrypted group password,
713the group ID and a list of the names of all group members. If no group with the
714given name or ID exists, then {{#f}} is returned.
715
716==== get-groups
717
718 [procedure] (get-groups)
719
720Returns a list with the supplementary group IDs of the current user.
721
722
723=== Changing user & group information
724
725==== set-groups!
726
727 [procedure] (set-groups! GIDLIST)
728
729Sets the supplementrary group IDs of the current user to the IDs given in the list {{GIDLIST}}.
730
731Only the superuser may invoke this procedure.
732
733==== initialize-groups
734
735 [procedure] (initialize-groups USERNAME BASEGID)
736
737Sets the supplementrary group IDs of the current user to the IDs from the user with name {{USERNAME}}
738(a string), including {{BASEGID}}.
739
740Only the superuser may invoke this procedure.
741
742==== set-process-group-id!
743
744 [procedure] (set-process-group-id! PID PGID)
745 [setter] (set! (process-group-id PID) PGID)
746
747Sets the process group ID of the process specifed by {{PID}} to {{PGID}}.
748
749
750=== Record locking
751
752==== file-lock
753
754 [procedure] (file-lock PORT [START [LEN]])
755
756Locks the file associated with {{PORT}} for reading or
757writing (according to whether {{PORT}} is an input- or
758output-port). {{START}} specifies the starting position in the
759file to be locked and defaults to 0. {{LEN}} specifies the length
760of the portion to be locked and defaults to {{#t}}, which means
761the complete file. {{file-lock}} returns a ''lock''-object.
762
763==== file-lock/blocking
764
765 [procedure] (file-lock/blocking PORT [START [LEN]])
766
767Similar to {{file-lock}}, but if a lock is held on the file,
768the current process blocks (including all threads) until the lock is released.
769
770==== file-test-lock
771
772 [procedure] (file-test-lock PORT [START [LEN]])
773
774Tests whether the file associated with {{PORT}} is locked for reading
775or writing (according to whether {{PORT}} is an input- or output-port)
776and returns either {{#f}} or the process-id of the locking process.
777
778==== file-unlock
779
780 [procedure] (file-unlock LOCK)
781
782Unlocks the previously locked portion of a file given in {{LOCK}}.
783
784
785=== Signal handling
786
787==== set-alarm!
788
789 [procedure] (set-alarm! SECONDS)
790
791Sets an internal timer to raise the {{signal/alrm}}
792after {{SECONDS}} are elapsed.  You can use the
793{{set-signal-handler!}} procedure to write a handler for this signal.
794
795==== set-signal-handler!
796
797 [procedure] (set-signal-handler! SIGNUM PROC)
798
799Establishes the procedure of one argument {{PROC}} as the handler
800for the signal with the code {{SIGNUM}}. {{PROC}} is called
801with the signal number as its sole argument. If the argument {{PROC}} is {{#f}}
802then any signal handler will be removed, and the corresponding signal set to {{SIG_IGN}}.
803
804Note that is is unspecified in which thread of execution the signal handler will be invoked.
805
806==== signal-handler
807
808 [procedure] (signal-handler SIGNUM)
809
810Returns the signal handler for the code {{SIGNUM}} or {{#f}}.
811
812==== set-signal-mask!
813
814 [procedure] (set-signal-mask! SIGLIST)
815
816Sets the signal mask of the current process to block all signals given
817in the list {{SIGLIST}}.  Signals masked in that way will not be
818delivered to the current process.
819
820==== signal-mask
821
822 [procedure] (signal-mask)
823
824Returns the signal mask of the current process.
825
826==== signal-masked?
827
828 [procedure] (signal-masked? SIGNUM)
829
830Returns whether the signal for the code {{SIGNUM}} is currently masked.
831
832==== signal-mask!
833
834 [procedure] (signal-mask! SIGNUM)
835
836Masks (blocks) the signal for the code {{SIGNUM}}.
837
838==== signal-unmask!
839
840 [procedure] (signal-unmask! SIGNUM)
841
842Unmasks (unblocks) the signal for the code {{SIGNUM}}.
843
844==== signal/term
845==== signal/kill
846==== signal/int
847==== signal/hup
848==== signal/fpe
849==== signal/ill
850==== signal/segv
851==== signal/abrt
852==== signal/trap
853==== signal/quit
854==== signal/alrm
855==== signal/vtalrm
856==== signal/prof
857==== signal/io
858==== signal/urg
859==== signal/chld
860==== signal/cont
861==== signal/stop
862==== signal/tstp
863==== signal/pipe
864==== signal/xcpu
865==== signal/xfsz
866==== signal/usr1
867==== signal/usr2
868==== signal/winch
869
870These variables contain signal codes for use with {{process-signal}},  {{set-signal-handler!}},  {{signal-handler}},  {{signal-masked?}},  {{signal-mask!}},  or {{signal-unmask!}}.
871
872
873=== Environment access
874
875==== current-environment
876
877 [procedure] (current-environment)
878
879Returns a association list of the environment variables and their
880current values.
881
882==== setenv
883
884 [procedure] (setenv VARIABLE VALUE)
885
886Sets the environment variable named {{VARIABLE}} to
887{{VALUE}}. Both arguments should be strings. If the variable is
888not defined in the environment, a new definition is created.
889
890==== unsetenv
891
892 [procedure] (unsetenv VARIABLE)
893
894Removes the definition of the environment variable {{VARIABLE}} from
895the environment of the current process. If the variable is not defined,
896nothing happens.
897
898
899=== Memory mapped I/O
900
901==== memory-mapped-file?
902
903 [pocedure] (memory-mapped-file? X)
904
905Returns {{#t}}, if {{X}} is an object representing a memory
906mapped file, or {{#f}} otherwise.
907
908==== map-file-to-memory
909
910 [procedure] (map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])
911
912Maps a section of a file to memory using the C function
913{{mmap()}}.  {{ADDRESS}} should be a foreign pointer object
914or {{#f}}; {{LEN}} specifies the size of the section to
915be mapped; {{PROTECTION}} should be one or more of the flags
916{{prot/read, prot/write, prot/exec}} or {{prot/none}}
917'''bitwise-ior'''ed together; {{FLAG}} should be one or more of
918the flags {{map/fixed, map/shared, map/private, map/anonymous}} or
919{{map/file}}; {{FILENO}} should be the file-descriptor of the
920mapped file. The optional argument {{OFFSET}} gives the offset of
921the section of the file to be mapped and defaults to 0. This procedure
922returns an object representing the mapped file section.  The procedure
923{{move-memory!}} can be used to access the mapped memory.
924
925==== memory-mapped-file-pointer
926
927 [procedure] (memory-mapped-file-pointer MMAP)
928
929Returns a machine pointer to the start of the memory region to which
930the file is mapped.
931
932==== unmap-file-from-memory
933
934 [procedure] (unmap-file-from-memory MMAP [LEN])
935
936Unmaps the section of a file mapped to memory using the C function
937{{munmap()}}.  {{MMAP}} should be a mapped file as returned
938by the procedure {{map-file-to-memory}}.  The optional argument
939{{LEN}} specifies the length of the section to be unmapped and
940defaults to the complete length given when the file was mapped.
941
942
943=== Date and time routines
944
945==== seconds->local-time
946
947 [procedure] (seconds->local-time SECONDS)
948
949Breaks down the time value represented in {{SECONDS}} into a 10
950element vector of the form {{#(seconds minutes hours mday month
951year wday yday dstflag timezone)}}, in the following format:
952
953; seconds (0) : the number of seconds after the minute (0 - 59)
954; minutes (1) : the number of minutes after the hour (0 - 59)
955; hours (2) : the number of hours past midnight (0 - 23)
956; mday (3) : the day of the month (1 - 31)
957; month (4) : the number of months since january (0 - 11)
958; year (5) : the number of years since 1900
959; wday (6) : the number of days since Sunday (0 - 6)
960; yday (7) : the number of days since January 1 (0 - 365)
961; dstflag (8) : a flag that is true if Daylight Saving Time is in effect at the time described.
962; timezone (9) : the difference between UTC and the latest local standard time, in seconds west of UTC.
963
964==== local-time->seconds
965
966 [procedure] (local-time->seconds VECTOR)
967
968Converts the ten-element vector {{VECTOR}} representing the time value relative to
969the current timezone into
970the number of seconds since the first of January, 1970 UTC.
971
972==== local-timezone-abbreviation
973
974 [procedure] (local-timezone-abbreviation)
975
976Returns the abbreviation for the local timezone as a string.
977
978==== seconds->string
979
980 [procedure] (seconds->string SECONDS)
981
982Converts the local time represented in {{SECONDS}} into a string
983of the form {{"Tue May 21 13:46:22 1991"}}.
984
985==== seconds->utc-time
986
987 [procedure] (seconds->utc-time SECONDS)
988
989Similar to {{seconds->local-time}}, but interpretes {{SECONDS}}
990as UTC time.
991
992==== utc-time->seconds
993
994 [procedure] (utc-time->seconds VECTOR)
995
996Converts the ten-element vector {{VECTOR}} representing the UTC time value into
997the number of seconds since the first of January, 1970 UTC.
998
999==== time->string
1000
1001 [procedure] (time->string VECTOR)
1002
1003Converts the broken down time represented in the 10 element vector
1004{{VECTOR}} into a string of the form {{"Tue May 21 13:46:22
10051991"}}.
1006
1007
1008=== Raw exit
1009
1010==== _exit
1011
1012 [procedure] (_exit [CODE])
1013
1014Exits the current process without flushing any buffered output (using
1015the C function {{_exit}}).  Note that the {{exit-handler}}
1016is not called when this procedure is invoked. The optional return-code
1017{{CODE}} defaults to {{0}}.
1018
1019
1020=== ERRNO values
1021
1022==== errno/perm
1023==== errno/noent
1024==== errno/srch
1025==== errno/intr
1026==== errno/io
1027==== errno/noexec
1028==== errno/badf
1029==== errno/child
1030==== errno/nomem
1031==== errno/acces
1032==== errno/fault
1033==== errno/busy
1034==== errno/notdir
1035==== errno/isdir
1036==== errno/inval
1037==== errno/mfile
1038==== errno/nospc
1039==== errno/spipe
1040==== errno/pipe
1041==== errno/again
1042==== errno/rofs
1043==== errno/exist
1044==== errno/wouldblock
1045These variables contain error codes as returned by {{errno}}.
1046
1047
1048=== Finding files
1049
1050==== find-files
1051
1052 [procedure] (find-files DIRECTORY PREDICATE [ACTION [IDENTITY [LIMIT]]])
1053
1054Recursively traverses the contents of {{DIRECTORY}} (which should
1055be a string) and invokes the procedure {{ACTION}} for all files
1056in which the procedure {{PREDICATE}} is true.  {{PREDICATE}}
1057may me a procedure of one argument or a regular-expression string.
1058{{ACTION}} should be a procedure of two arguments: the currently
1059encountered file and the result of the previous invocation of
1060{{ACTION}}, or, if this is the first invocation, the value
1061of {{IDENTITY}}. {{ACTION}} defaults to {{cons}},
1062{{IDENTITY}} defaults to {{()}}.  {{LIMIT}} should be a
1063procedure of one argument that is called for each nested directory
1064and which should return true, if that directory is to be traversed
1065recursively. {{LIMIT}} may also be an exact integer that
1066gives the maximum recursion depth. For example, a depth of {{0}} means that only files in the top-level, specified directory are to be traversed. In this case, all nested directories are ignored.  {{LIMIT}} may also be {{#f}} (the default),
1067which is equivalent to {{(constantly #t)}}.
1068
1069Note that {{ACTION}} is called with the full pathname of each file,
1070including the directory prefix.
1071
1072
1073=== Getting the hostname and system information
1074
1075==== get-host-name
1076
1077 [procedure] (get-host-name)
1078
1079Returns the hostname of the machine that this process is running on.
1080
1081==== system-information
1082
1083 [procedure] (system-information)
1084
1085Invokes the UNIX system call {{uname()}} and returns a list of 5 values:
1086system-name, node-name, OS release, OS version and machine.
1087
1088=== Setting the file buffering mode
1089
1090==== set-buffering-mode!
1091
1092 [procedure] (set-buffering-mode! PORT MODE [BUFSIZE])
1093
1094Sets the buffering-mode for the file associated with {{PORT}} to
1095{{MODE}}, which should be one of the keywords {{#:full}},
1096{{#:line}} or {{#:none}}. If {{BUFSIZE}} is specified it
1097determines the size of the buffer to be used (if any).
1098
1099
1100=== Terminal ports
1101
1102==== terminal-name
1103
1104 [procedure] (terminal-name PORT)
1105
1106Returns the name of the terminal that is connected to {{PORT}}.
1107
1108==== terminal-port?
1109
1110 [procedure] (terminal-port? PORT)
1111
1112Returns {{#t}} if {{PORT}} is connected to a terminal and
1113{{#f}} otherwise.
1114
1115
1116=== How Scheme procedures relate to UNIX C functions
1117
1118; {{change-directory}} : {{chdir}}
1119; {{change-file-mode}} : {{chmod}}
1120; {{change-file-owner}} : {{chown}}
1121; {{create-directory}} : {{mkdir}}
1122; {{create-fifo}} : {{mkfifo}}
1123; {{create-pipe}} : {{pipe}}
1124; {{create-session}} : {{setsid}}
1125; {{create-symbolic-link}} : {{link}}
1126; {{current-directory}} : {{curdir}}
1127; {{current-effective-groupd-id}} : {{getegid}}
1128; {{current-effective-user-id}} : {{geteuid}}
1129; {{current-group-id}} : {{getgid}}
1130; {{current-parent-id}} : {{getppid}}
1131; {{current-process-id}} : {{getpid}}
1132; {{current-user-id}} : {{getuid}}
1133; {{delete-directory}} : {{rmdir}}
1134; {{duplicate-fileno}} : {{dup/dup2}}
1135; {{_exit}} : {{_exit}}
1136; {{file-close}} : {{close}}
1137; {{file-access-time}} : {{stat}}
1138; {{file-change-time}} : {{stat}}
1139; {{file-modification-time}} : {{stat}}
1140; {{file-execute-access?}} : {{access}}
1141; {{file-open}} : {{open}}
1142; {{file-lock}} : {{fcntl}}
1143; {{file-position}} : {{ftell/lseek}}
1144; {{file-read}} : {{read}}
1145; {{file-read-access?}} : {{access}}
1146; {{file-select}} : {{select}}
1147; {{file-control}} : {{fcntl}}
1148; {{file-stat}} : {{stat}}
1149; {{file-test-lock}} : {{fcntl}}
1150; {{file-truncate}} : {{truncate/ftruncate}}
1151; {{file-unlock}} : {{fcntl}}
1152; {{file-write}} : {{write}}
1153; {{file-write-access?}} : {{access}}
1154; {{get-groups}} : {{getgroups}}
1155; {{get-host-name}} : {{gethostname}}
1156; {{initialize-groups}} : {{initgroups}}
1157; {{local-time->seconds}} : {{mktime}}
1158; {{local-timezone-abbreviation}} : {{localtime}}
1159; {{map-file-to-memory}} : {{mmap}}
1160; {{open-input-file*}} : {{fdopen}}
1161; {{open-output-file*}} : {{fdopen}}
1162; {{open-input-pipe}} : {{popen}}
1163; {{open-output-pipe}} : {{popen}}
1164; {{port->fileno}} : {{fileno}}
1165; {{process-execute}} : {{execvp}}
1166; {{process-fork}} : {{fork}}
1167; {{process-group-id}} : {{getpgid}}
1168; {{process-signal}} : {{kill}}
1169; {{process-wait}} : {{waitpid}}
1170; {{close-input-pipe}} : {{pclose}}
1171; {{close-output-pipe}} : {{pclose}}
1172; {{read-symbolic-link}} : {{readlink}}
1173; {{seconds->local-time}} : {{localtime}}
1174; {{seconds->string}} : {{ctime}}
1175; {{seconds->utc-time}} : {{gmtime}}
1176; {{set-alarm!}} : {{alarm}}
1177; {{set-buffering-mode!}} : {{setvbuf}}
1178; {{set-file-position!}} : {{fseek/seek}}
1179; {{set-groups!}} : {{setgroups}}
1180; {{set-signal-mask!}} : {{sigprocmask}}
1181; {{set-group-id!}} : {{setgid}}
1182; {{set-process-group-id!}} : {{setpgid}}
1183; {{set-user-id!}} : {{setuid}}
1184; {{set-root-directory!}} : {{chroot}}
1185; {{setenv}} : {{setenv/putenv}}
1186; {{sleep}} : {{sleep}}
1187; {{system-information}} : {{uname}}
1188; {{terminal-name}} : {{ttyname}}
1189; {{terminal-port?}} : {{isatty}}
1190; {{time->string}} : {{asctime}}
1191; {{unsetenv}} : {{putenv}}
1192; {{unmap-file-from-memory}} : {{munmap}}
1193; {{user-information}} : {{getpwnam/getpwuid}}
1194; {{utc-time->seconds}} : {{timegm}}
1195
1196
1197=== Windows specific notes
1198
1199Use of UTF8 encoded strings is for pathnames is not supported. Windows uses a
120016-bit UNICODE encoding with special system calls for wide-character support.
1201Only single-byte string encoding can be used.
1202
1203==== Procedure Changes
1204
1205Exceptions to the above procedure definitions.
1206
1207 [procedure] (create-pipe [MODE])
1208
1209The optional parameter {{MODE}}, default {{open/binary | open/noinherit}}. This can be {{open/binary}} or
1210{{open/text}}, optionally or'ed with {{open/noinherit}}.
1211
1212 [procedure] (process-wait [PID [NOHANG]])
1213
1214{{process-wait}} always returns {{#t}} for a terminated process and only the exit
1215status is available. (Windows does not provide signals as an interprocess
1216communication method.)
1217
1218 [procedure] (process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])
1219 [procedure] (process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])
1220 [procedure] (process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])
1221
1222The optional parameter {{EXACT-FLAG}}, default {{#f}}. When {{#f}} any argument string with
1223embedded whitespace will be wrapped in quotes. When {{#t}} no such wrapping occurs.
1224
1225==== Unsupported Definitions
1226
1227The following definitions are not supported for native Windows builds (compiled with the
1228Microsoft tools or with MinGW):
1229
1230 open/noctty  open/nonblock  open/fsync  open/sync
1231 perm/isvtx  perm/isuid  perm/isgid
1232 file-select file-control
1233 signal/... (except signal/term, signal/int, signal/fpe, signal/ill, signal/segv, signal/abrt, signal/break)
1234 set-signal-mask!  signal-mask  signal-masked?  signal-mask!  signal-unmask!
1235 user-information  group-information  get-groups  set-groups!  initialize-groups
1236 errno/wouldblock
1237 change-file-owner
1238 current-user-id  current-group-id  current-effective-user-id  current-effective-groupd-id
1239 set-user-id!  set-group-id!
1240 create-session
1241 process-group-id  set-process-group-id!
1242 create-symbolic-link  read-symbolic-link
1243 file-truncate
1244 file-lock  file-lock/blocking  file-unlock  file-test-lock
1245 create-fifo  fifo?
1246 prot/...
1247 map/...
1248 map-file-to-memory  unmap-file-from-memory  memory-mapped-file-pointer  memory-mapped-file?
1249 set-alarm!
1250 terminal-port?  terminal-name
1251 process-fork  process-signal
1252 parent-process-id
1253 set-root-directory!
1254 utc-time->seconds
1255
1256==== Additional Definitions
1257
1258Only available for Windows
1259
1260* open/noinherit
1261
1262This variable is a mode value for {{create-pipe}}. Useful when spawning a child process.
1263
1264* spawn/overlay
1265* spawn/wait
1266* spawn/nowait
1267* spawn/nowaito
1268* spawn/detach
1269
1270These variables contains special flags that specify the exact semantics of {{process-spawn}}:
1271{{spawn/overlay}} replaces the current process with the new one.
1272{{spawn/wait}} suspends execution of the current process until the spawned process returns.
1273{{spawn/nowait}} does the opposite ({{spawn/nowaito}} is identical, according to the Microsoft
1274documentation) and runs the process asynchronously.
1275{{spawn/detach}} runs the new process in the background, without being attached to a console.
1276
1277==== process-spawn
1278
1279 [procedure] (process-spawn MODE COMMAND [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])
1280
1281Creates and runs a new process with the given {{COMMAND}} filename and the optional
1282{{ARGUMENT-LIST}} and {{ENVIRONMENT-LIST}}. {{MODE}} specifies how exactly the process
1283should be executed and must be one or more of the {{spawn/...}} flags defined above.
1284
1285The {{EXACT-FLAG}}, default {{#f}}, controls quote-wrapping of argument strings. When {{#t}}
1286quote-wrapping is not performed.
1287
1288Returns:
1289* the exit status when synchronous
1290* the PID when asynchronous
1291* -1 when failure
1292
1293
1294Previous: [[Unit srfi-18]]
1295
1296Next: [[Unit utils]]
Note: See TracBrowser for help on using the repository browser.