source: project/chicken/branches/prerelease/manual/Unit posix @ 13859

Last change on this file since 13859 was 13859, checked in by felix winkelmann, 11 years ago

merged trunk rev. 13858 (not including srandom change)

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