1Unix(3)                          OCaml library                         Unix(3)
2
3
4

NAME

6       Unix - Interface to the Unix system.
7

Module

9       Module   Unix
10

Documentation

12       Module Unix
13        : sig end
14
15
16       Interface to the Unix system.
17
18       To use the labeled version of this module, add module Unix = UnixLabels
19       in your implementation.
20
21       Note: all the functions of this module (except  Unix.error_message  and
22       Unix.handle_unix_error ) are liable to raise the Unix.Unix_error excep‐
23       tion whenever the underlying system call signals an error.
24
25
26
27
28
29
30
31   Error report
32       type error =
33        | E2BIG  (* Argument list too long
34        *)
35        | EACCES  (* Permission denied
36        *)
37        | EAGAIN  (* Resource temporarily unavailable; try again
38        *)
39        | EBADF  (* Bad file descriptor
40        *)
41        | EBUSY  (* Resource unavailable
42        *)
43        | ECHILD  (* No child process
44        *)
45        | EDEADLK  (* Resource deadlock would occur
46        *)
47        | EDOM  (* Domain error for math functions, etc.
48        *)
49        | EEXIST  (* File exists
50        *)
51        | EFAULT  (* Bad address
52        *)
53        | EFBIG  (* File too large
54        *)
55        | EINTR  (* Function interrupted by signal
56        *)
57        | EINVAL  (* Invalid argument
58        *)
59        | EIO  (* Hardware I/O error
60        *)
61        | EISDIR  (* Is a directory
62        *)
63        | EMFILE  (* Too many open files by the process
64        *)
65        | EMLINK  (* Too many links
66        *)
67        | ENAMETOOLONG  (* Filename too long
68        *)
69        | ENFILE  (* Too many open files in the system
70        *)
71        | ENODEV  (* No such device
72        *)
73        | ENOENT  (* No such file or directory
74        *)
75        | ENOEXEC  (* Not an executable file
76        *)
77        | ENOLCK  (* No locks available
78        *)
79        | ENOMEM  (* Not enough memory
80        *)
81        | ENOSPC  (* No space left on device
82        *)
83        | ENOSYS  (* Function not supported
84        *)
85        | ENOTDIR  (* Not a directory
86        *)
87        | ENOTEMPTY  (* Directory not empty
88        *)
89        | ENOTTY  (* Inappropriate I/O control operation
90        *)
91        | ENXIO  (* No such device or address
92        *)
93        | EPERM  (* Operation not permitted
94        *)
95        | EPIPE  (* Broken pipe
96        *)
97        | ERANGE  (* Result too large
98        *)
99        | EROFS  (* Read-only file system
100        *)
101        | ESPIPE  (* Invalid seek e.g. on a pipe
102        *)
103        | ESRCH  (* No such process
104        *)
105        | EXDEV  (* Invalid link
106        *)
107        | EWOULDBLOCK  (* Operation would block
108        *)
109        | EINPROGRESS  (* Operation now in progress
110        *)
111        | EALREADY  (* Operation already in progress
112        *)
113        | ENOTSOCK  (* Socket operation on non-socket
114        *)
115        | EDESTADDRREQ  (* Destination address required
116        *)
117        | EMSGSIZE  (* Message too long
118        *)
119        | EPROTOTYPE  (* Protocol wrong type for socket
120        *)
121        | ENOPROTOOPT  (* Protocol not available
122        *)
123        | EPROTONOSUPPORT  (* Protocol not supported
124        *)
125        | ESOCKTNOSUPPORT  (* Socket type not supported
126        *)
127        | EOPNOTSUPP  (* Operation not supported on socket
128        *)
129        | EPFNOSUPPORT  (* Protocol family not supported
130        *)
131        | EAFNOSUPPORT  (* Address family not supported by protocol family
132        *)
133        | EADDRINUSE  (* Address already in use
134        *)
135        | EADDRNOTAVAIL  (* Can't assign requested address
136        *)
137        | ENETDOWN  (* Network is down
138        *)
139        | ENETUNREACH  (* Network is unreachable
140        *)
141        | ENETRESET  (* Network dropped connection on reset
142        *)
143        | ECONNABORTED  (* Software caused connection abort
144        *)
145        | ECONNRESET  (* Connection reset by peer
146        *)
147        | ENOBUFS  (* No buffer space available
148        *)
149        | EISCONN  (* Socket is already connected
150        *)
151        | ENOTCONN  (* Socket is not connected
152        *)
153        | ESHUTDOWN  (* Can't send after socket shutdown
154        *)
155        | ETOOMANYREFS  (* Too many references: can't splice
156        *)
157        | ETIMEDOUT  (* Connection timed out
158        *)
159        | ECONNREFUSED  (* Connection refused
160        *)
161        | EHOSTDOWN  (* Host is down
162        *)
163        | EHOSTUNREACH  (* No route to host
164        *)
165        | ELOOP  (* Too many levels of symbolic links
166        *)
167        | EOVERFLOW  (* File size or position not representable
168        *)
169        | EUNKNOWNERR of int
170         (* Unknown error
171        *)
172
173
174       The type of error codes.  Errors defined in the POSIX standard and  ad‐
175       ditional  errors  from  UNIX98 and BSD.  All other errors are mapped to
176       EUNKNOWNERR.
177
178
179
180       exception Unix_error of error * string * string
181
182
183       Raised by the system calls below when an  error  is  encountered.   The
184       first component is the error code; the second component is the function
185       name; the third component is the string parameter to the  function,  if
186       it has one, or the empty string otherwise.
187
188
189       UnixLabels.Unix_error  and  Unix.Unix_error  are the same, and catching
190       one will catch the other.
191
192
193
194       val error_message : error -> string
195
196       Return a string describing the given error code.
197
198
199
200       val handle_unix_error : ('a -> 'b) -> 'a -> 'b
201
202
203       handle_unix_error f x applies f to x and returns the  result.   If  the
204       exception Unix.Unix_error is raised, it prints a message describing the
205       error and exits with code 2.
206
207
208
209
210   Access to the process environment
211       val environment : unit -> string array
212
213       Return the process environment, as an array of strings with the  format
214       ``variable=value''.   The  returned  array  is empty if the process has
215       special privileges.
216
217
218
219       val unsafe_environment : unit -> string array
220
221       Return the process environment, as an array of strings with the  format
222       ``variable=value''.   Unlike Unix.environment , this function returns a
223       populated array even if the process has special  privileges.   See  the
224       documentation for Unix.unsafe_getenv for more details.
225
226
227       Since 4.06.0 (4.12.0 in UnixLabels)
228
229
230
231       val getenv : string -> string
232
233       Return  the  value associated to a variable in the process environment,
234       unless the process has special privileges.
235
236
237       Raises Not_found if the variable is unbound or the process has  special
238       privileges.
239
240       This function is identical to Sys.getenv .
241
242
243
244       val unsafe_getenv : string -> string
245
246       Return the value associated to a variable in the process environment.
247
248       Unlike  Unix.getenv  ,  this  function  returns  the  value even if the
249       process has special privileges. It is  considered  unsafe  because  the
250       programmer of a setuid or setgid program must be careful to avoid using
251       maliciously crafted environment variables in the search path  for  exe‐
252       cutables, the locations for temporary files or logs, and the like.
253
254
255       Since 4.06.0
256
257
258       Raises Not_found if the variable is unbound.
259
260
261
262       val putenv : string -> string -> unit
263
264
265       putenv  name  value  sets  the  value  associated  to a variable in the
266       process environment.  name is the name of the environment variable, and
267       value its new associated value.
268
269
270
271
272   Process handling
273       type process_status =
274        | WEXITED of int
275         (*  The process terminated normally by exit ; the argument is the re‐
276       turn code.
277        *)
278        | WSIGNALED of int
279         (* The process was killed by a signal; the  argument  is  the  signal
280       number.
281        *)
282        | WSTOPPED of int
283         (*  The  process  was stopped by a signal; the argument is the signal
284       number.
285        *)
286
287
288       The termination status of a process.  See module Sys  for  the  defini‐
289       tions  of the standard signal numbers.  Note that they are not the num‐
290       bers used by the OS.
291
292
293       type wait_flag =
294        | WNOHANG  (* Do not block if no child has died yet,  but  immediately
295       return with a pid equal to 0.
296        *)
297        | WUNTRACED  (* Report also the children that receive stop signals.
298        *)
299
300
301       Flags for Unix.waitpid .
302
303
304
305       val execv : string -> string array -> 'a
306
307
308       execv  prog  args execute the program in file prog , with the arguments
309       args , and the current process  environment.   These  execv*  functions
310       never  return:  on  success, the current program is replaced by the new
311       one.
312
313
314       Raises Unix_error on failure
315
316
317
318       val execve : string -> string array -> string array -> 'a
319
320       Same as Unix.execv , except that the third argument provides the  envi‐
321       ronment to the program executed.
322
323
324
325       val execvp : string -> string array -> 'a
326
327       Same as Unix.execv , except that the program is searched in the path.
328
329
330
331       val execvpe : string -> string array -> string array -> 'a
332
333       Same as Unix.execve , except that the program is searched in the path.
334
335
336
337       val fork : unit -> int
338
339       Fork  a  new  process. The returned integer is 0 for the child process,
340       the pid of the child process for the parent process.
341
342       On Windows: not implemented, use Unix.create_process or threads.
343
344
345
346       val wait : unit -> int * process_status
347
348       Wait until one of the children processes die, and return  its  pid  and
349       termination status.
350
351       On Windows: not implemented, use Unix.waitpid .
352
353
354
355       val waitpid : wait_flag list -> int -> int * process_status
356
357       Same as Unix.wait , but waits for the child process whose pid is given.
358       A pid of -1 means wait for any child.  A pid of 0 means  wait  for  any
359       child  in  the same process group as the current process.  Negative pid
360       arguments represent process groups.   The  list  of  options  indicates
361       whether  waitpid should return immediately without waiting, and whether
362       it should report stopped children.
363
364       On Windows: can only wait for a given PID, not any child process.
365
366
367
368       val system : string -> process_status
369
370       Execute the given command, wait until it  terminates,  and  return  its
371       termination  status. The string is interpreted by the shell /bin/sh (or
372       the command interpreter cmd.exe on Windows) and therefore  can  contain
373       redirections, quotes, variables, etc.  To properly quote whitespace and
374       shell special characters occurring in file names or command  arguments,
375       the  use  of Filename.quote_command is recommended.  The result WEXITED
376       127 indicates that the shell couldn't be executed.
377
378
379
380       val _exit : int -> 'a
381
382       Terminate the calling process immediately, returning the  given  status
383       code  to  the  operating system: usually 0 to indicate no errors, and a
384       small positive integer to indicate failure.  Unlike exit  ,  Unix._exit
385       performs  no finalization whatsoever: functions registered with at_exit
386       are not called, input/output  channels  are  not  flushed,  and  the  C
387       run-time system is not finalized either.
388
389       The  typical use of Unix._exit is after a Unix.fork operation, when the
390       child process runs into a fatal error and must exit.  In this case,  it
391       is  preferable  to  not  perform  any  finalization action in the child
392       process, as these actions could interfere  with  similar  actions  per‐
393       formed  by the parent process.  For example, output channels should not
394       be flushed by the child process, as the parent process may  flush  them
395       again later, resulting in duplicate output.
396
397
398       Since 4.12.0
399
400
401
402       val getpid : unit -> int
403
404       Return the pid of the process.
405
406
407
408       val getppid : unit -> int
409
410       Return the pid of the parent process.
411
412       On Windows: not implemented (because it is meaningless).
413
414
415
416       val nice : int -> int
417
418       Change  the  process  priority.  The  integer  argument is added to the
419       ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
420       ties.) Return the new nice value.
421
422       On Windows: not implemented.
423
424
425
426
427   Basic file input/output
428       type file_descr
429
430
431       The abstract type of file descriptors.
432
433
434
435       val stdin : file_descr
436
437       File descriptor for standard input.
438
439
440
441       val stdout : file_descr
442
443       File descriptor for standard output.
444
445
446
447       val stderr : file_descr
448
449       File descriptor for standard error.
450
451
452       type open_flag =
453        | O_RDONLY  (* Open for reading
454        *)
455        | O_WRONLY  (* Open for writing
456        *)
457        | O_RDWR  (* Open for reading and writing
458        *)
459        | O_NONBLOCK  (* Open in non-blocking mode
460        *)
461        | O_APPEND  (* Open for append
462        *)
463        | O_CREAT  (* Create if nonexistent
464        *)
465        | O_TRUNC  (* Truncate to 0 length if existing
466        *)
467        | O_EXCL  (* Fail if existing
468        *)
469        | O_NOCTTY  (* Don't make this dev a controlling tty
470        *)
471        | O_DSYNC  (* Writes complete as `Synchronised I/O data integrity com‐
472       pletion'
473        *)
474        | O_SYNC  (* Writes complete as `Synchronised I/O file integrity  com‐
475       pletion'
476        *)
477        | O_RSYNC  (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
478        *)
479        |  O_SHARE_DELETE  (* Windows only: allow the file to be deleted while
480       still open
481        *)
482        | O_CLOEXEC  (* Set the close-on-exec flag on the descriptor  returned
483       by Unix.openfile .  See Unix.set_close_on_exec for more information.
484        *)
485        |  O_KEEPEXEC  (* Clear the close-on-exec flag.  This is currently the
486       default.
487        *)
488
489
490       The flags to Unix.openfile .
491
492
493       type file_perm = int
494
495
496       The type of file access rights, e.g.  0o640 is read and write for user,
497       read for group, none for others
498
499
500
501       val openfile : string -> open_flag list -> file_perm -> file_descr
502
503       Open the named file with the given flags. Third argument is the permis‐
504       sions to give to the file if it is created (see Unix.umask ). Return  a
505       file descriptor on the named file.
506
507
508
509       val close : file_descr -> unit
510
511       Close a file descriptor.
512
513
514
515       val fsync : file_descr -> unit
516
517       Flush file buffers to disk.
518
519
520       Since 4.08.0 (4.12.0 in UnixLabels)
521
522
523
524       val read : file_descr -> bytes -> int -> int -> int
525
526
527       read  fd  buf pos len reads len bytes from descriptor fd , storing them
528       in byte sequence buf , starting at position pos in  buf  .  Return  the
529       number of bytes actually read.
530
531
532
533       val write : file_descr -> bytes -> int -> int -> int
534
535
536       write  fd  buf  pos len writes len bytes to descriptor fd , taking them
537       from byte sequence buf , starting at position pos in buff . Return  the
538       number  of bytes actually written.  write repeats the writing operation
539       until all bytes have been written or an error occurs.
540
541
542
543       val single_write : file_descr -> bytes -> int -> int -> int
544
545       Same as Unix.write , but attempts to write only once.  Thus, if an  er‐
546       ror occurs, single_write guarantees that no data has been written.
547
548
549
550       val write_substring : file_descr -> string -> int -> int -> int
551
552       Same  as Unix.write , but take the data from a string instead of a byte
553       sequence.
554
555
556       Since 4.02.0
557
558
559
560       val single_write_substring : file_descr -> string -> int -> int -> int
561
562       Same as Unix.single_write , but take the data from a string instead  of
563       a byte sequence.
564
565
566       Since 4.02.0
567
568
569
570
571   Interfacing with the standard input/output library
572       val in_channel_of_descr : file_descr -> in_channel
573
574       Create an input channel reading from the given descriptor.  The channel
575       is initially in binary mode; use set_binary_mode_in ic  false  if  text
576       mode  is desired.  Text mode is supported only if the descriptor refers
577       to a file or pipe, but is not supported if it refers to a socket.
578
579       On Windows: set_binary_mode_in always fails on  channels  created  with
580       this function.
581
582       Beware  that  input  channels are buffered, so more characters may have
583       been read from the descriptor than those accessed using  channel  func‐
584       tions.  Channels also keep a copy of the current position in the file.
585
586       Closing  the  channel  ic  returned  by  in_channel_of_descr  fd  using
587       close_in ic also closes the underlying descriptor fd .  It is incorrect
588       to close both the channel ic and the descriptor fd .
589
590       If  several  channels  are  created  on the same descriptor, one of the
591       channels must be closed, but not the others.  Consider  for  example  a
592       descriptor  s  connected  to  a  socket  and two channels ic = in_chan‐
593       nel_of_descr s and oc = out_channel_of_descr s .  The recommended clos‐
594       ing protocol is to perform close_out oc , which flushes buffered output
595       to the socket then closes the socket.   The  ic  channel  must  not  be
596       closed and will be collected by the GC eventually.
597
598
599
600       val out_channel_of_descr : file_descr -> out_channel
601
602       Create  an output channel writing on the given descriptor.  The channel
603       is initially in binary mode; use set_binary_mode_out oc false  if  text
604       mode  is desired.  Text mode is supported only if the descriptor refers
605       to a file or pipe, but is not supported if it refers to a socket.
606
607       On Windows: set_binary_mode_out always fails on channels  created  with
608       this function.
609
610       Beware that output channels are buffered, so you may have to call flush
611       to ensure that all data has been sent to the descriptor.  Channels also
612       keep a copy of the current position in the file.
613
614       Closing  the  channel  oc  returned  by  out_channel_of_descr  fd using
615       close_out oc also closes the underlying descriptor fd .  It  is  incor‐
616       rect to close both the channel ic and the descriptor fd .
617
618       See  Unix.in_channel_of_descr  for a discussion of the closing protocol
619       when several channels are created on the same descriptor.
620
621
622
623       val descr_of_in_channel : in_channel -> file_descr
624
625       Return the descriptor corresponding to an input channel.
626
627
628
629       val descr_of_out_channel : out_channel -> file_descr
630
631       Return the descriptor corresponding to an output channel.
632
633
634
635
636   Seeking and truncating
637       type seek_command =
638        | SEEK_SET  (* indicates positions relative to the  beginning  of  the
639       file
640        *)
641        | SEEK_CUR  (* indicates positions relative to the current position
642        *)
643        | SEEK_END  (* indicates positions relative to the end of the file
644        *)
645
646
647       Positioning modes for Unix.lseek .
648
649
650
651       val lseek : file_descr -> int -> seek_command -> int
652
653       Set  the current position for a file descriptor, and return the result‐
654       ing offset (from the beginning of the file).
655
656
657
658       val truncate : string -> int -> unit
659
660       Truncates the named file to the given size.
661
662
663
664       val ftruncate : file_descr -> int -> unit
665
666       Truncates the file corresponding to the given descriptor to  the  given
667       size.
668
669
670
671
672   File status
673       type file_kind =
674        | S_REG  (* Regular file
675        *)
676        | S_DIR  (* Directory
677        *)
678        | S_CHR  (* Character device
679        *)
680        | S_BLK  (* Block device
681        *)
682        | S_LNK  (* Symbolic link
683        *)
684        | S_FIFO  (* Named pipe
685        *)
686        | S_SOCK  (* Socket
687        *)
688
689
690
691
692       type stats = {
693        st_dev : int ;  (* Device number
694        *)
695        st_ino : int ;  (* Inode number
696        *)
697        st_kind : file_kind ;  (* Kind of the file
698        *)
699        st_perm : file_perm ;  (* Access rights
700        *)
701        st_nlink : int ;  (* Number of links
702        *)
703        st_uid : int ;  (* User id of the owner
704        *)
705        st_gid : int ;  (* Group ID of the file's group
706        *)
707        st_rdev : int ;  (* Device ID (if special file)
708        *)
709        st_size : int ;  (* Size in bytes
710        *)
711        st_atime : float ;  (* Last access time
712        *)
713        st_mtime : float ;  (* Last modification time
714        *)
715        st_ctime : float ;  (* Last status change time
716        *)
717        }
718
719
720       The information returned by the Unix.stat calls.
721
722
723
724       val stat : string -> stats
725
726       Return the information for the named file.
727
728
729
730       val lstat : string -> stats
731
732       Same as Unix.stat , but in case the file is a symbolic link, return the
733       information for the link itself.
734
735
736
737       val fstat : file_descr -> stats
738
739       Return the information for the file associated with the given  descrip‐
740       tor.
741
742
743
744       val isatty : file_descr -> bool
745
746       Return  true  if the given file descriptor refers to a terminal or con‐
747       sole window, false otherwise.
748
749
750
751
752   File operations on large files
753       module LargeFile : sig end
754
755
756       File operations on large files.  This sub-module provides 64-bit  vari‐
757       ants  of the functions Unix.LargeFile.lseek (for positioning a file de‐
758       scriptor), Unix.LargeFile.truncate  and  Unix.LargeFile.ftruncate  (for
759       changing  the  size  of  a file), and Unix.LargeFile.stat , Unix.Large‐
760       File.lstat  and  Unix.LargeFile.fstat  (for  obtaining  information  on
761       files).   These  alternate  functions  represent positions and sizes by
762       64-bit integers (type int64 ) instead of regular integers (type int  ),
763       thus allowing operating on files whose sizes are greater than max_int .
764
765
766
767
768   Mapping files into memory
769       val map_file : file_descr -> ?pos:int64 -> ('a, 'b) Bigarray.kind -> 'c
770       Bigarray.layout -> bool -> int array -> ('a,  'b,  'c)  Bigarray.Genar‐
771       ray.t
772
773       Memory mapping of a file as a Bigarray.  map_file fd kind layout shared
774       dims returns a Bigarray of kind kind , layout layout ,  and  dimensions
775       as  specified  in  dims  .  The data contained in this Bigarray are the
776       contents of the file referred to by the file descriptor fd  (as  opened
777       previously with Unix.openfile , for example).  The optional pos parame‐
778       ter is the byte offset in the file of the data  being  mapped;  it  de‐
779       faults to 0 (map from the beginning of the file).
780
781       If  shared  is  true , all modifications performed on the array are re‐
782       flected in the file.  This requires that fd be opened with  write  per‐
783       missions.   If  shared  is false , modifications performed on the array
784       are done in memory only, using copy-on-write of the modified pages; the
785       underlying file is not affected.
786
787
788       Genarray.map_file is much more efficient than reading the whole file in
789       a Bigarray, modifying that Bigarray, and writing it afterwards.
790
791       To adjust automatically the dimensions of the Bigarray  to  the  actual
792       size of the file, the major dimension (that is, the first dimension for
793       an array with C layout, and the last dimension for an array  with  For‐
794       tran  layout)  can  be given as -1 .  Genarray.map_file then determines
795       the major dimension from the size of the file.  The file  must  contain
796       an  integral number of sub-arrays as determined by the non-major dimen‐
797       sions, otherwise Failure is raised.
798
799       If all dimensions of the Bigarray are given, the file size  is  matched
800       against  the  size of the Bigarray.  If the file is larger than the Bi‐
801       garray, only the initial portion of the file is mapped to the Bigarray.
802       If  the  file  is smaller than the big array, the file is automatically
803       grown to the size of the Bigarray.  This requires write permissions  on
804       fd .
805
806       Array accesses are bounds-checked, but the bounds are determined by the
807       initial call to map_file . Therefore, you should  make  sure  no  other
808       process modifies the mapped file while you're accessing it, or a SIGBUS
809       signal may be raised. This  happens,  for  instance,  if  the  file  is
810       shrunk.
811
812
813       Invalid_argument or Failure may be raised in cases where argument vali‐
814       dation fails.
815
816
817       Since 4.06.0
818
819
820
821
822   Operations on file names
823       val unlink : string -> unit
824
825       Removes the named file.
826
827       If the named file is a directory, raises:
828
829       - EPERM on POSIX compliant system
830
831       - EISDIR on Linux >= 2.1.132
832
833       - EACCESS on Windows
834
835
836
837
838       val rename : string -> string -> unit
839
840
841       rename src dst changes the name of a file from src to dst ,  moving  it
842       between  directories  if  needed.   If dst already exists, its contents
843       will be replaced with those of src .  Depending on the  operating  sys‐
844       tem,  the  metadata (permissions, owner, etc) of dst can either be pre‐
845       served or be replaced by those of src .
846
847
848
849       val link : ?follow:bool -> string -> string -> unit
850
851
852       link ?follow src dst creates a hard link named dst to  the  file  named
853       src .
854
855
856       Raises ENOSYS On Unix if ~follow:_ is requested, but linkat is unavail‐
857       able.
858
859
860       Raises ENOSYS On Windows if ~follow:false is requested.
861
862
863
864       val realpath : string -> string
865
866
867       realpath p is an absolute pathname for p obtained by resolving all  ex‐
868       tra / characters, relative path segments and symbolic links.
869
870
871       Since 4.13.0
872
873
874
875
876   File permissions and ownership
877       type access_permission =
878        | R_OK  (* Read permission
879        *)
880        | W_OK  (* Write permission
881        *)
882        | X_OK  (* Execution permission
883        *)
884        | F_OK  (* File exists
885        *)
886
887
888       Flags for the Unix.access call.
889
890
891
892       val chmod : string -> file_perm -> unit
893
894       Change the permissions of the named file.
895
896
897
898       val fchmod : file_descr -> file_perm -> unit
899
900       Change the permissions of an opened file.
901
902       On Windows: not implemented.
903
904
905
906       val chown : string -> int -> int -> unit
907
908       Change the owner uid and owner gid of the named file.
909
910       On Windows: not implemented.
911
912
913
914       val fchown : file_descr -> int -> int -> unit
915
916       Change the owner uid and owner gid of an opened file.
917
918       On Windows: not implemented.
919
920
921
922       val umask : int -> int
923
924       Set  the  process's  file  mode  creation mask, and return the previous
925       mask.
926
927       On Windows: not implemented.
928
929
930
931       val access : string -> access_permission list -> unit
932
933       Check that the process has the given permissions over the named file.
934
935       On Windows: execute permission X_OK cannot be tested,  just  tests  for
936       read permission instead.
937
938
939       Raises Unix_error otherwise.
940
941
942
943
944   Operations on file descriptors
945       val dup : ?cloexec:bool -> file_descr -> file_descr
946
947       Return a new file descriptor referencing the same file as the given de‐
948       scriptor.  See Unix.set_close_on_exec for documentation on the  cloexec
949       optional argument.
950
951
952
953       val dup2 : ?cloexec:bool -> file_descr -> file_descr -> unit
954
955
956       dup2  src  dst  duplicates  src to dst , closing dst if already opened.
957       See Unix.set_close_on_exec for documentation on  the  cloexec  optional
958       argument.
959
960
961
962       val set_nonblock : file_descr -> unit
963
964       Set  the  ``non-blocking''  flag  on  the  given  descriptor.  When the
965       non-blocking flag is set, reading on a descriptor  on  which  there  is
966       temporarily  no  data  available raises the EAGAIN or EWOULDBLOCK error
967       instead of blocking; writing on a descriptor on which there  is  tempo‐
968       rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
969
970
971
972       val clear_nonblock : file_descr -> unit
973
974       Clear   the   ``non-blocking''  flag  on  the  given  descriptor.   See
975       Unix.set_nonblock .
976
977
978
979       val set_close_on_exec : file_descr -> unit
980
981       Set the ``close-on-exec'' flag on the given descriptor.   A  descriptor
982       with  the  close-on-exec  flag is automatically closed when the current
983       process starts another program with one of the  exec  ,  create_process
984       and open_process functions.
985
986       It  is often a security hole to leak file descriptors opened on, say, a
987       private file to an external program: the program, then, gets access  to
988       the  private  file  and can do bad things with it.  Hence, it is highly
989       recommended to set all file descriptors  ``close-on-exec'',  except  in
990       the  very few cases where a file descriptor actually needs to be trans‐
991       mitted to another program.
992
993       The best way to set a file descriptor ``close-on-exec'' is to create it
994       in  this  state.   To this end, the openfile function has O_CLOEXEC and
995       O_KEEPEXEC flags to enforce ``close-on-exec'' mode or  ``keep-on-exec''
996       mode,  respectively.  All other operations in the Unix module that cre‐
997       ate file descriptors have an optional argument ?cloexec:bool  to  indi‐
998       cate whether the file descriptor should be created in ``close-on-exec''
999       mode (by writing ~cloexec:true ) or in ``keep-on-exec'' mode (by  writ‐
1000       ing  ~cloexec:false  ).   For  historical reasons, the default file de‐
1001       scriptor creation mode is ``keep-on-exec'', if no cloexec optional  ar‐
1002       gument is given.  This is not a safe default, hence it is highly recom‐
1003       mended to pass explicit cloexec arguments  to  operations  that  create
1004       file descriptors.
1005
1006       The  cloexec optional arguments and the O_KEEPEXEC flag were introduced
1007       in OCaml 4.05.  Earlier, the common practice was  to  create  file  de‐
1008       scriptors   in   the   default,   ``keep-on-exec''   mode,   then  call
1009       set_close_on_exec on those freshly-created file descriptors.   This  is
1010       not  as  safe as creating the file descriptor in ``close-on-exec'' mode
1011       because, in multithreaded programs, a window  of  vulnerability  exists
1012       between  the  time  when  the  file  descriptor is created and the time
1013       set_close_on_exec completes.  If another thread spawns another  program
1014       during  this  window,  the  descriptor will leak, as it is still in the
1015       ``keep-on-exec'' mode.
1016
1017       Regarding the atomicity guarantees given by ~cloexec:true or by the use
1018       of the O_CLOEXEC flag: on all platforms it is guaranteed that a concur‐
1019       rently-executing Caml thread cannot leak the descriptor by  starting  a
1020       new  process.  On Linux, this guarantee extends to concurrently-execut‐
1021       ing C threads.  As of Feb 2017, other operating systems lack the neces‐
1022       sary  system  calls  and  still expose a window of vulnerability during
1023       which  a  C  thread  can  see  the  newly-created  file  descriptor  in
1024       ``keep-on-exec'' mode.
1025
1026
1027
1028       val clear_close_on_exec : file_descr -> unit
1029
1030       Clear   the  ``close-on-exec''  flag  on  the  given  descriptor.   See
1031       Unix.set_close_on_exec .
1032
1033
1034
1035
1036   Directories
1037       val mkdir : string -> file_perm -> unit
1038
1039       Create a directory with the given permissions (see Unix.umask ).
1040
1041
1042
1043       val rmdir : string -> unit
1044
1045       Remove an empty directory.
1046
1047
1048
1049       val chdir : string -> unit
1050
1051       Change the process working directory.
1052
1053
1054
1055       val getcwd : unit -> string
1056
1057       Return the name of the current working directory.
1058
1059
1060
1061       val chroot : string -> unit
1062
1063       Change the process root directory.
1064
1065       On Windows: not implemented.
1066
1067
1068       type dir_handle
1069
1070
1071       The type of descriptors over opened directories.
1072
1073
1074
1075       val opendir : string -> dir_handle
1076
1077       Open a descriptor on a directory
1078
1079
1080
1081       val readdir : dir_handle -> string
1082
1083       Return the next entry in a directory.
1084
1085
1086       Raises End_of_file when the end of the directory has been reached.
1087
1088
1089
1090       val rewinddir : dir_handle -> unit
1091
1092       Reposition the descriptor to the beginning of the directory
1093
1094
1095
1096       val closedir : dir_handle -> unit
1097
1098       Close a directory descriptor.
1099
1100
1101
1102
1103   Pipes and redirections
1104       val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
1105
1106       Create a pipe. The first component of the result is opened for reading,
1107       that's  the  exit to the pipe. The second component is opened for writ‐
1108       ing, that's the entrance to the pipe.  See  Unix.set_close_on_exec  for
1109       documentation on the cloexec optional argument.
1110
1111
1112
1113       val mkfifo : string -> file_perm -> unit
1114
1115       Create a named pipe with the given permissions (see Unix.umask ).
1116
1117       On Windows: not implemented.
1118
1119
1120
1121
1122   High-level process and redirection management
1123       val create_process : string -> string array -> file_descr -> file_descr
1124       -> file_descr -> int
1125
1126
1127       create_process prog args stdin stdout stderr forks a new  process  that
1128       executes  the  program  in file prog , with arguments args . The pid of
1129       the new process is returned immediately; the new process executes  con‐
1130       currently  with the current process.  The standard input and outputs of
1131       the new process are connected to the descriptors  stdin  ,  stdout  and
1132       stderr .  Passing e.g.  Stdlib.stdout for stdout prevents the redirect‐
1133       ion and causes the new process to have the same standard output as  the
1134       current  process.   The  executable  file prog is searched in the path.
1135       The new process has the same environment as the current process.
1136
1137
1138
1139       val create_process_env : string -> string  array  ->  string  array  ->
1140       file_descr -> file_descr -> file_descr -> int
1141
1142
1143       create_process_env prog args env stdin stdout stderr works as Unix.cre‐
1144       ate_process , except that the extra argument env specifies the environ‐
1145       ment passed to the program.
1146
1147
1148
1149       val open_process_in : string -> in_channel
1150
1151       High-level  pipe  and  process management. This function runs the given
1152       command in parallel with the program.  The standard output of the  com‐
1153       mand  is redirected to a pipe, which can be read via the returned input
1154       channel.  The command is interpreted by the shell /bin/sh  (or  cmd.exe
1155       on  Windows),  cf.   Unix.system .  The Filename.quote_command function
1156       can be used to quote the command and its arguments as  appropriate  for
1157       the  shell  being used.  If the command does not need to be run through
1158       the shell, Unix.open_process_args_in can be used as a more  robust  and
1159       more efficient alternative to Unix.open_process_in .
1160
1161
1162
1163       val open_process_out : string -> out_channel
1164
1165       Same  as  Unix.open_process_in , but redirect the standard input of the
1166       command to a pipe.  Data written to the returned output channel is sent
1167       to  the standard input of the command.  Warning: writes on output chan‐
1168       nels are buffered, hence be careful to call flush at the right times to
1169       ensure correct synchronization.  If the command does not need to be run
1170       through the shell, Unix.open_process_args_out can be  used  instead  of
1171       Unix.open_process_out .
1172
1173
1174
1175       val open_process : string -> in_channel * out_channel
1176
1177       Same  as  Unix.open_process_out , but redirects both the standard input
1178       and standard output of the command to pipes connected to  the  two  re‐
1179       turned  channels.   The input channel is connected to the output of the
1180       command, and the output channel to the input of the  command.   If  the
1181       command    does    not    need   to   be   run   through   the   shell,
1182       Unix.open_process_args can be used instead of Unix.open_process .
1183
1184
1185
1186       val  open_process_full  :  string  ->  string  array  ->  in_channel  *
1187       out_channel * in_channel
1188
1189       Similar  to  Unix.open_process  , but the second argument specifies the
1190       environment passed to the command.  The result is a triple of  channels
1191       connected  respectively  to  the  standard  output, standard input, and
1192       standard error of the command.  If the command does not need to be  run
1193       through  the  shell, Unix.open_process_args_full can be used instead of
1194       Unix.open_process_full .
1195
1196
1197
1198       val open_process_args_in : string -> string array -> in_channel
1199
1200
1201       open_process_args_in prog args runs the  program  prog  with  arguments
1202       args .  The new process executes concurrently with the current process.
1203       The standard output of the new process is redirected to a  pipe,  which
1204       can be read via the returned input channel.
1205
1206       The  executable  file  prog  is  searched  in  the path. This behaviour
1207       changed in 4.12; previously prog was looked up only in the current  di‐
1208       rectory.
1209
1210       The new process has the same environment as the current process.
1211
1212
1213       Since 4.08.0
1214
1215
1216
1217       val open_process_args_out : string -> string array -> out_channel
1218
1219       Same  as Unix.open_process_args_in , but redirect the standard input of
1220       the new process to a pipe.  Data written to the returned output channel
1221       is  sent to the standard input of the program.  Warning: writes on out‐
1222       put channels are buffered, hence be careful to call flush at the  right
1223       times to ensure correct synchronization.
1224
1225
1226       Since 4.08.0
1227
1228
1229
1230       val  open_process_args  :  string  ->  string  array  ->  in_channel  *
1231       out_channel
1232
1233       Same as Unix.open_process_args_out , but redirects  both  the  standard
1234       input  and standard output of the new process to pipes connected to the
1235       two returned channels.  The input channel is connected to the output of
1236       the program, and the output channel to the input of the program.
1237
1238
1239       Since 4.08.0
1240
1241
1242
1243       val  open_process_args_full : string -> string array -> string array ->
1244       in_channel * out_channel * in_channel
1245
1246       Similar to Unix.open_process_args , but the  third  argument  specifies
1247       the  environment  passed to the new process.  The result is a triple of
1248       channels connected respectively to the standard output, standard input,
1249       and standard error of the program.
1250
1251
1252       Since 4.08.0
1253
1254
1255
1256       val process_in_pid : in_channel -> int
1257
1258       Return  the  pid  of  a  process  opened  via  Unix.open_process_in  or
1259       Unix.open_process_args_in .
1260
1261
1262       Since 4.08.0 (4.12.0 in UnixLabels)
1263
1264
1265
1266       val process_out_pid : out_channel -> int
1267
1268       Return the  pid  of  a  process  opened  via  Unix.open_process_out  or
1269       Unix.open_process_args_out .
1270
1271
1272       Since 4.08.0 (4.12.0 in UnixLabels)
1273
1274
1275
1276       val process_pid : in_channel * out_channel -> int
1277
1278       Return   the   pid   of  a  process  opened  via  Unix.open_process  or
1279       Unix.open_process_args .
1280
1281
1282       Since 4.08.0 (4.12.0 in UnixLabels)
1283
1284
1285
1286       val process_full_pid : in_channel * out_channel * in_channel -> int
1287
1288       Return the pid  of  a  process  opened  via  Unix.open_process_full  or
1289       Unix.open_process_args_full .
1290
1291
1292       Since 4.08.0 (4.12.0 in UnixLabels)
1293
1294
1295
1296       val close_process_in : in_channel -> process_status
1297
1298       Close channels opened by Unix.open_process_in , wait for the associated
1299       command to terminate, and return its termination status.
1300
1301
1302
1303       val close_process_out : out_channel -> process_status
1304
1305       Close channels opened by Unix.open_process_out , wait for  the  associ‐
1306       ated command to terminate, and return its termination status.
1307
1308
1309
1310       val close_process : in_channel * out_channel -> process_status
1311
1312       Close  channels  opened  by Unix.open_process , wait for the associated
1313       command to terminate, and return its termination status.
1314
1315
1316
1317       val close_process_full :  in_channel  *  out_channel  *  in_channel  ->
1318       process_status
1319
1320       Close  channels opened by Unix.open_process_full , wait for the associ‐
1321       ated command to terminate, and return its termination status.
1322
1323
1324
1325
1326   Symbolic links
1327       val symlink : ?to_dir:bool -> string -> string -> unit
1328
1329
1330       symlink ?to_dir src dst creates the file dst as a symbolic link to  the
1331       file  src . On Windows, to_dir indicates if the symbolic link points to
1332       a directory or a file; if omitted, symlink examines src using stat  and
1333       picks  appropriately,  if src does not exist then false is assumed (for
1334       this reason, it is recommended that the to_dir parameter  be  specified
1335       in new code). On Unix, to_dir is ignored.
1336
1337       Windows  symbolic  links  are available in Windows Vista onwards. There
1338       are some important differences between Windows symlinks and their POSIX
1339       counterparts.
1340
1341       Windows  symbolic  links  come  in two flavours: directory and regular,
1342       which designate whether the symbolic link points to a  directory  or  a
1343       file.  The  type  must  be correct - a directory symlink which actually
1344       points to a file cannot be selected with chdir and a file symlink which
1345       actually  points  to  a  directory cannot be read or written (note that
1346       Cygwin's emulation layer ignores this distinction).
1347
1348       When symbolic links are created to existing targets,  this  distinction
1349       doesn't  matter  and symlink will automatically create the correct kind
1350       of symbolic link. The distinction matters when a symbolic link is  cre‐
1351       ated to a non-existent target.
1352
1353       The other caveat is that by default symbolic links are a privileged op‐
1354       eration. Administrators will always need to  be  running  elevated  (or
1355       with  UAC  disabled)  and  by  default  normal user accounts need to be
1356       granted the SeCreateSymbolicLinkPrivilege  via  Local  Security  Policy
1357       (secpol.msc) or via Active Directory.
1358
1359
1360       Unix.has_symlink  can be used to check that a process is able to create
1361       symbolic links.
1362
1363
1364
1365       val has_symlink : unit -> bool
1366
1367       Returns true if the user is able to create symbolic links. On  Windows,
1368       this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1369       ilege but is also running elevated, if necessary. On  other  platforms,
1370       this is simply indicates that the symlink system call is available.
1371
1372
1373       Since 4.03.0
1374
1375
1376
1377       val readlink : string -> string
1378
1379       Read the contents of a symbolic link.
1380
1381
1382
1383
1384   Polling
1385       val  select  : file_descr list -> file_descr list -> file_descr list ->
1386       float -> file_descr list * file_descr list * file_descr list
1387
1388       Wait until some input/output operations become possible on  some  chan‐
1389       nels.  The three list arguments are, respectively, a set of descriptors
1390       to check for reading (first argument), for writing  (second  argument),
1391       or for exceptional conditions (third argument).  The fourth argument is
1392       the maximal timeout, in seconds; a negative fourth  argument  means  no
1393       timeout  (unbounded wait).  The result is composed of three sets of de‐
1394       scriptors: those ready for reading (first component), ready for writing
1395       (second  component), and over which an exceptional condition is pending
1396       (third component).
1397
1398
1399
1400
1401   Locking
1402       type lock_command =
1403        | F_ULOCK  (* Unlock a region
1404        *)
1405        | F_LOCK  (* Lock a region for writing, and block if already locked
1406        *)
1407        | F_TLOCK  (* Lock a region for writing, or fail if already locked
1408        *)
1409        | F_TEST  (* Test a region for other process locks
1410        *)
1411        | F_RLOCK  (* Lock a region for reading, and block if already locked
1412        *)
1413        | F_TRLOCK  (* Lock a region for reading, or fail if already locked
1414        *)
1415
1416
1417       Commands for Unix.lockf .
1418
1419
1420
1421       val lockf : file_descr -> lock_command -> int -> unit
1422
1423
1424       lockf fd mode len puts a lock on a region of the file opened  as  fd  .
1425       The  region starts at the current read/write position for fd (as set by
1426       Unix.lseek ), and extends len bytes forward if  len  is  positive,  len
1427       bytes backwards if len is negative, or to the end of the file if len is
1428       zero.  A write lock prevents any other process from acquiring a read or
1429       write  lock on the region.  A read lock prevents any other process from
1430       acquiring a write lock on the region, but lets other processes  acquire
1431       read locks on it.
1432
1433       The  F_LOCK  and  F_TLOCK  commands attempts to put a write lock on the
1434       specified region.  The F_RLOCK and F_TRLOCK commands attempts to put  a
1435       read  lock on the specified region.  If one or several locks put by an‐
1436       other process prevent the current  process  from  acquiring  the  lock,
1437       F_LOCK  and  F_RLOCK block until these locks are removed, while F_TLOCK
1438       and F_TRLOCK fail immediately with an exception.  The  F_ULOCK  removes
1439       whatever  locks  the  current process has on the specified region.  Fi‐
1440       nally, the F_TEST command tests whether a write lock can be acquired on
1441       the  specified region, without actually putting a lock.  It returns im‐
1442       mediately if successful, or fails otherwise.
1443
1444       What happens when a process tries to lock a region of a  file  that  is
1445       already locked by the same process depends on the OS.  On POSIX-compli‐
1446       ant systems, the second lock operation succeeds and may  "promote"  the
1447       older  lock  from read lock to write lock.  On Windows, the second lock
1448       operation will block or fail.
1449
1450
1451
1452
1453   Signals
1454       Note: installation of signal handlers is performed  via  the  functions
1455       Sys.signal and Sys.set_signal .
1456
1457       val kill : int -> int -> unit
1458
1459
1460       kill pid signal sends signal number signal to the process with id pid .
1461
1462       On Windows: only the Sys.sigkill signal is emulated.
1463
1464
1465       type sigprocmask_command =
1466        | SIG_SETMASK
1467        | SIG_BLOCK
1468        | SIG_UNBLOCK
1469
1470
1471
1472
1473
1474       val sigprocmask : sigprocmask_command -> int list -> int list
1475
1476
1477       sigprocmask  mode  sigs changes the set of blocked signals.  If mode is
1478       SIG_SETMASK , blocked signals are set to those in the list sigs  .   If
1479       mode is SIG_BLOCK , the signals in sigs are added to the set of blocked
1480       signals.  If mode is SIG_UNBLOCK , the signals in sigs are removed from
1481       the  set of blocked signals.  sigprocmask returns the set of previously
1482       blocked signals.
1483
1484       When the systhreads version of the Thread module is loaded, this  func‐
1485       tion  redirects  to Thread.sigmask . I.e., sigprocmask only changes the
1486       mask of the current thread.
1487
1488       On Windows: not implemented (no inter-process signals on Windows).
1489
1490
1491
1492       val sigpending : unit -> int list
1493
1494       Return the set of blocked signals that are currently pending.
1495
1496       On Windows: not implemented (no inter-process signals on Windows).
1497
1498
1499
1500       val sigsuspend : int list -> unit
1501
1502
1503       sigsuspend sigs atomically sets the blocked signals to sigs  and  waits
1504       for  a non-ignored, non-blocked signal to be delivered.  On return, the
1505       blocked signals are reset to their initial value.
1506
1507       On Windows: not implemented (no inter-process signals on Windows).
1508
1509
1510
1511       val pause : unit -> unit
1512
1513       Wait until a non-ignored, non-blocked signal is delivered.
1514
1515       On Windows: not implemented (no inter-process signals on Windows).
1516
1517
1518
1519
1520   Time functions
1521       type process_times = {
1522        tms_utime : float ;  (* User time for the process
1523        *)
1524        tms_stime : float ;  (* System time for the process
1525        *)
1526        tms_cutime : float ;  (* User time for the children processes
1527        *)
1528        tms_cstime : float ;  (* System time for the children processes
1529        *)
1530        }
1531
1532
1533       The execution times (CPU times) of a process.
1534
1535
1536       type tm = {
1537        tm_sec : int ;  (* Seconds 0..60
1538        *)
1539        tm_min : int ;  (* Minutes 0..59
1540        *)
1541        tm_hour : int ;  (* Hours 0..23
1542        *)
1543        tm_mday : int ;  (* Day of month 1..31
1544        *)
1545        tm_mon : int ;  (* Month of year 0..11
1546        *)
1547        tm_year : int ;  (* Year - 1900
1548        *)
1549        tm_wday : int ;  (* Day of week (Sunday is 0)
1550        *)
1551        tm_yday : int ;  (* Day of year 0..365
1552        *)
1553        tm_isdst : bool ;  (* Daylight time savings in effect
1554        *)
1555        }
1556
1557
1558       The type representing wallclock time and calendar date.
1559
1560
1561
1562       val time : unit -> float
1563
1564       Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1565
1566
1567
1568       val gettimeofday : unit -> float
1569
1570       Same as Unix.time , but with resolution better than 1 second.
1571
1572
1573
1574       val gmtime : float -> tm
1575
1576       Convert a time in seconds, as returned by Unix.time , into a date and a
1577       time.  Assumes UTC (Coordinated Universal Time), also known as GMT.  To
1578       perform the inverse conversion, set  the  TZ  environment  variable  to
1579       "UTC", use Unix.mktime , and then restore the original value of TZ.
1580
1581
1582
1583       val localtime : float -> tm
1584
1585       Convert a time in seconds, as returned by Unix.time , into a date and a
1586       time. Assumes the local time zone.  The function performing the inverse
1587       conversion is Unix.mktime .
1588
1589
1590
1591       val mktime : tm -> float * tm
1592
1593       Convert  a  date and time, specified by the tm argument, into a time in
1594       seconds, as returned by Unix.time .  The tm_isdst , tm_wday and tm_yday
1595       fields  of  tm are ignored.  Also return a normalized copy of the given
1596       tm record, with the tm_wday , tm_yday , and tm_isdst fields  recomputed
1597       from  the other fields, and the other fields normalized (so that, e.g.,
1598       40 October is changed into 9 November).  The tm argument is interpreted
1599       in the local time zone.
1600
1601
1602
1603       val alarm : int -> int
1604
1605       Schedule a SIGALRM signal after the given number of seconds.
1606
1607       On Windows: not implemented.
1608
1609
1610
1611       val sleep : int -> unit
1612
1613       Stop execution for the given number of seconds.
1614
1615
1616
1617       val sleepf : float -> unit
1618
1619       Stop execution for the given number of seconds.  Like sleep , but frac‐
1620       tions of seconds are supported.
1621
1622
1623       Since 4.03.0 (4.12.0 in UnixLabels)
1624
1625
1626
1627       val times : unit -> process_times
1628
1629       Return the execution times of the process.
1630
1631       On Windows: partially implemented, will not report  timings  for  child
1632       processes.
1633
1634
1635
1636       val utimes : string -> float -> float -> unit
1637
1638       Set the last access time (second arg) and last modification time (third
1639       arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1640       1,  1970.   If  both  times  are 0.0 , the access and last modification
1641       times are both set to the current time.
1642
1643
1644       type interval_timer =
1645        | ITIMER_REAL  (* decrements  in  real  time,  and  sends  the  signal
1646       SIGALRM when expired.
1647        *)
1648        |  ITIMER_VIRTUAL   (*  decrements  in process virtual time, and sends
1649       SIGVTALRM when expired.
1650        *)
1651        | ITIMER_PROF  (* (for profiling) decrements both when the process  is
1652       running  and  when  the  system is running on behalf of the process; it
1653       sends SIGPROF when expired.
1654        *)
1655
1656
1657       The three kinds of interval timers.
1658
1659
1660       type interval_timer_status = {
1661        it_interval : float ;  (* Period
1662        *)
1663        it_value : float ;  (* Current value of the timer
1664        *)
1665        }
1666
1667
1668       The type describing the status of an interval timer
1669
1670
1671
1672       val getitimer : interval_timer -> interval_timer_status
1673
1674       Return the current status of the given interval timer.
1675
1676       On Windows: not implemented.
1677
1678
1679
1680       val setitimer  :  interval_timer  ->  interval_timer_status  ->  inter‐
1681       val_timer_status
1682
1683
1684       setitimer  t  s sets the interval timer t and returns its previous sta‐
1685       tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1686       is  the  time to the next timer expiration; s.it_interval , if nonzero,
1687       specifies a value to be used in reloading it_value when the  timer  ex‐
1688       pires.   Setting  s.it_value  to  zero  disables  the  timer.   Setting
1689       s.it_interval to zero causes the timer to be disabled  after  its  next
1690       expiration.
1691
1692       On Windows: not implemented.
1693
1694
1695
1696
1697   User id, group id
1698       val getuid : unit -> int
1699
1700       Return the user id of the user executing the process.
1701
1702       On Windows: always returns 1 .
1703
1704
1705
1706       val geteuid : unit -> int
1707
1708       Return the effective user id under which the process runs.
1709
1710       On Windows: always returns 1 .
1711
1712
1713
1714       val setuid : int -> unit
1715
1716       Set the real user id and effective user id for the process.
1717
1718       On Windows: not implemented.
1719
1720
1721
1722       val getgid : unit -> int
1723
1724       Return the group id of the user executing the process.
1725
1726       On Windows: always returns 1 .
1727
1728
1729
1730       val getegid : unit -> int
1731
1732       Return the effective group id under which the process runs.
1733
1734       On Windows: always returns 1 .
1735
1736
1737
1738       val setgid : int -> unit
1739
1740       Set the real group id and effective group id for the process.
1741
1742       On Windows: not implemented.
1743
1744
1745
1746       val getgroups : unit -> int array
1747
1748       Return  the  list of groups to which the user executing the process be‐
1749       longs.
1750
1751       On Windows: always returns [|1|] .
1752
1753
1754
1755       val setgroups : int array -> unit
1756
1757
1758       setgroups groups sets the  supplementary  group  IDs  for  the  calling
1759       process. Appropriate privileges are required.
1760
1761       On Windows: not implemented.
1762
1763
1764
1765       val initgroups : string -> int -> unit
1766
1767
1768       initgroups  user group initializes the group access list by reading the
1769       group database /etc/group and using all groups of which user is a  mem‐
1770       ber. The additional group group is also added to the list.
1771
1772       On Windows: not implemented.
1773
1774
1775       type passwd_entry = {
1776        pw_name : string ;
1777        pw_passwd : string ;
1778        pw_uid : int ;
1779        pw_gid : int ;
1780        pw_gecos : string ;
1781        pw_dir : string ;
1782        pw_shell : string ;
1783        }
1784
1785
1786       Structure of entries in the passwd database.
1787
1788
1789       type group_entry = {
1790        gr_name : string ;
1791        gr_passwd : string ;
1792        gr_gid : int ;
1793        gr_mem : string array ;
1794        }
1795
1796
1797       Structure of entries in the groups database.
1798
1799
1800
1801       val getlogin : unit -> string
1802
1803       Return the login name of the user executing the process.
1804
1805
1806
1807       val getpwnam : string -> passwd_entry
1808
1809       Find an entry in passwd with the given name.
1810
1811
1812       Raises Not_found if no such entry exists, or always on Windows.
1813
1814
1815
1816       val getgrnam : string -> group_entry
1817
1818       Find an entry in group with the given name.
1819
1820
1821       Raises Not_found if no such entry exists, or always on Windows.
1822
1823
1824
1825       val getpwuid : int -> passwd_entry
1826
1827       Find an entry in passwd with the given user id.
1828
1829
1830       Raises Not_found if no such entry exists, or always on Windows.
1831
1832
1833
1834       val getgrgid : int -> group_entry
1835
1836       Find an entry in group with the given group id.
1837
1838
1839       Raises Not_found if no such entry exists, or always on Windows.
1840
1841
1842
1843
1844   Internet addresses
1845       type inet_addr
1846
1847
1848       The abstract type of Internet addresses.
1849
1850
1851
1852       val inet_addr_of_string : string -> inet_addr
1853
1854       Conversion  from the printable representation of an Internet address to
1855       its internal representation.  The argument string consists of 4 numbers
1856       separated  by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1857       8 numbers separated by colons for IPv6 addresses.
1858
1859
1860       Raises Failure when given a string that does not match these formats.
1861
1862
1863
1864       val string_of_inet_addr : inet_addr -> string
1865
1866       Return the printable representation of the given Internet address.  See
1867       Unix.inet_addr_of_string for a description of the printable representa‐
1868       tion.
1869
1870
1871
1872       val inet_addr_any : inet_addr
1873
1874       A special IPv4 address, for use only with bind , representing  all  the
1875       Internet addresses that the host machine possesses.
1876
1877
1878
1879       val inet_addr_loopback : inet_addr
1880
1881       A special IPv4 address representing the host machine ( 127.0.0.1 ).
1882
1883
1884
1885       val inet6_addr_any : inet_addr
1886
1887       A  special  IPv6 address, for use only with bind , representing all the
1888       Internet addresses that the host machine possesses.
1889
1890
1891
1892       val inet6_addr_loopback : inet_addr
1893
1894       A special IPv6 address representing the host machine ( ::1 ).
1895
1896
1897
1898       val is_inet6_addr : inet_addr -> bool
1899
1900       Whether the given inet_addr is an IPv6 address.
1901
1902
1903       Since 4.12.0
1904
1905
1906
1907
1908   Sockets
1909       type socket_domain =
1910        | PF_UNIX  (* Unix domain
1911        *)
1912        | PF_INET  (* Internet domain (IPv4)
1913        *)
1914        | PF_INET6  (* Internet domain (IPv6)
1915        *)
1916
1917
1918       The type of socket domains.  Not all  platforms  support  IPv6  sockets
1919       (type PF_INET6 ).
1920
1921       On Windows: PF_UNIX not implemented.
1922
1923
1924       type socket_type =
1925        | SOCK_STREAM  (* Stream socket
1926        *)
1927        | SOCK_DGRAM  (* Datagram socket
1928        *)
1929        | SOCK_RAW  (* Raw socket
1930        *)
1931        | SOCK_SEQPACKET  (* Sequenced packets socket
1932        *)
1933
1934
1935       The  type  of socket kinds, specifying the semantics of communications.
1936       SOCK_SEQPACKET is included for completeness, but is rarely supported by
1937       the OS, and needs system calls that are not available in this library.
1938
1939
1940       type sockaddr =
1941        | ADDR_UNIX of string
1942        | ADDR_INET of inet_addr * int
1943
1944
1945       The  type  of  socket addresses.  ADDR_UNIX name is a socket address in
1946       the  Unix  domain;  name  is  a  file  name   in   the   file   system.
1947       ADDR_INET(addr,port)  is  a socket address in the Internet domain; addr
1948       is the Internet address of the machine, and port is the port number.
1949
1950
1951
1952       val socket : ?cloexec:bool -> socket_domain -> socket_type  ->  int  ->
1953       file_descr
1954
1955       Create  a  new socket in the given domain, and with the given kind. The
1956       third argument is the protocol type; 0 selects the default protocol for
1957       that  kind of sockets.  See Unix.set_close_on_exec for documentation on
1958       the cloexec optional argument.
1959
1960
1961
1962       val domain_of_sockaddr : sockaddr -> socket_domain
1963
1964       Return the socket domain adequate for the given socket address.
1965
1966
1967
1968       val socketpair : ?cloexec:bool -> socket_domain -> socket_type  ->  int
1969       -> file_descr * file_descr
1970
1971       Create   a   pair   of   unnamed   sockets,  connected  together.   See
1972       Unix.set_close_on_exec for documentation on the cloexec optional  argu‐
1973       ment.
1974
1975
1976
1977       val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
1978
1979       Accept  connections  on  the given socket. The returned descriptor is a
1980       socket connected to the client; the returned address is the address  of
1981       the connecting client.  See Unix.set_close_on_exec for documentation on
1982       the cloexec optional argument.
1983
1984
1985
1986       val bind : file_descr -> sockaddr -> unit
1987
1988       Bind a socket to an address.
1989
1990
1991
1992       val connect : file_descr -> sockaddr -> unit
1993
1994       Connect a socket to an address.
1995
1996
1997
1998       val listen : file_descr -> int -> unit
1999
2000       Set up a socket for receiving connection requests. The integer argument
2001       is the maximal number of pending requests.
2002
2003
2004       type shutdown_command =
2005        | SHUTDOWN_RECEIVE  (* Close for receiving
2006        *)
2007        | SHUTDOWN_SEND  (* Close for sending
2008        *)
2009        | SHUTDOWN_ALL  (* Close both
2010        *)
2011
2012
2013       The type of commands for shutdown .
2014
2015
2016
2017       val shutdown : file_descr -> shutdown_command -> unit
2018
2019       Shutdown  a socket connection.  SHUTDOWN_SEND as second argument causes
2020       reads on the other end of the connection to return an end-of-file  con‐
2021       dition.  SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
2022       tion to return a closed pipe condition ( SIGPIPE signal).
2023
2024
2025
2026       val getsockname : file_descr -> sockaddr
2027
2028       Return the address of the given socket.
2029
2030
2031
2032       val getpeername : file_descr -> sockaddr
2033
2034       Return the address of the host connected to the given socket.
2035
2036
2037       type msg_flag =
2038        | MSG_OOB
2039        | MSG_DONTROUTE
2040        | MSG_PEEK
2041
2042
2043       The flags for Unix.recv , Unix.recvfrom , Unix.send and Unix.sendto .
2044
2045
2046
2047       val recv : file_descr -> bytes -> int -> int -> msg_flag list -> int
2048
2049       Receive data from a connected socket.
2050
2051
2052
2053       val recvfrom : file_descr -> bytes -> int -> int ->  msg_flag  list  ->
2054       int * sockaddr
2055
2056       Receive data from an unconnected socket.
2057
2058
2059
2060       val send : file_descr -> bytes -> int -> int -> msg_flag list -> int
2061
2062       Send data over a connected socket.
2063
2064
2065
2066       val  send_substring  :  file_descr  -> string -> int -> int -> msg_flag
2067       list -> int
2068
2069       Same as send , but take the data from a string instead of  a  byte  se‐
2070       quence.
2071
2072
2073       Since 4.02.0
2074
2075
2076
2077       val  sendto  :  file_descr  ->  bytes -> int -> int -> msg_flag list ->
2078       sockaddr -> int
2079
2080       Send data over an unconnected socket.
2081
2082
2083
2084       val sendto_substring : file_descr -> string -> int -> int  ->  msg_flag
2085       list -> sockaddr -> int
2086
2087       Same  as sendto , but take the data from a string instead of a byte se‐
2088       quence.
2089
2090
2091       Since 4.02.0
2092
2093
2094
2095
2096   Socket options
2097       type socket_bool_option =
2098        | SO_DEBUG  (* Record debugging information
2099        *)
2100        | SO_BROADCAST  (* Permit sending of broadcast messages
2101        *)
2102        | SO_REUSEADDR  (* Allow reuse of local addresses for bind
2103        *)
2104        | SO_KEEPALIVE  (* Keep connection active
2105        *)
2106        | SO_DONTROUTE  (* Bypass the standard routing algorithms
2107        *)
2108        | SO_OOBINLINE  (* Leave out-of-band data in line
2109        *)
2110        | SO_ACCEPTCONN  (* Report whether socket listening is enabled
2111        *)
2112        | TCP_NODELAY  (* Control the Nagle algorithm for TCP sockets
2113        *)
2114        | IPV6_ONLY  (* Forbid binding an IPv6 socket to an IPv4 address
2115        *)
2116        | SO_REUSEPORT  (* Allow reuse of address and port bindings
2117        *)
2118
2119
2120       The socket options that can be consulted with Unix.getsockopt and modi‐
2121       fied  with  Unix.setsockopt  .   These  options have a boolean ( true /
2122       false ) value.
2123
2124
2125       type socket_int_option =
2126        | SO_SNDBUF  (* Size of send buffer
2127        *)
2128        | SO_RCVBUF  (* Size of received buffer
2129        *)
2130        | SO_ERROR  (* Deprecated.  Use Unix.getsockopt_error instead.
2131        *)
2132        | SO_TYPE  (* Report the socket type
2133        *)
2134        | SO_RCVLOWAT  (* Minimum number of bytes to process for input  opera‐
2135       tions
2136        *)
2137        | SO_SNDLOWAT  (* Minimum number of bytes to process for output opera‐
2138       tions
2139        *)
2140
2141
2142       The socket options that can be consulted with  Unix.getsockopt_int  and
2143       modified  with  Unix.setsockopt_int  .   These  options have an integer
2144       value.
2145
2146
2147       type socket_optint_option =
2148        | SO_LINGER  (* Whether to linger on closed connections that have data
2149       present, and for how long (in seconds)
2150        *)
2151
2152
2153       The  socket  options  that can be consulted with Unix.getsockopt_optint
2154       and modified with Unix.setsockopt_optint .  These options have a  value
2155       of type int option , with None meaning ``disabled''.
2156
2157
2158       type socket_float_option =
2159        | SO_RCVTIMEO  (* Timeout for input operations
2160        *)
2161        | SO_SNDTIMEO  (* Timeout for output operations
2162        *)
2163
2164
2165       The socket options that can be consulted with Unix.getsockopt_float and
2166       modified with Unix.setsockopt_float .   These  options  have  a  float‐
2167       ing-point  value representing a time in seconds.  The value 0 means in‐
2168       finite timeout.
2169
2170
2171
2172       val getsockopt : file_descr -> socket_bool_option -> bool
2173
2174       Return the current status of  a  boolean-valued  option  in  the  given
2175       socket.
2176
2177
2178
2179       val setsockopt : file_descr -> socket_bool_option -> bool -> unit
2180
2181       Set or clear a boolean-valued option in the given socket.
2182
2183
2184
2185       val getsockopt_int : file_descr -> socket_int_option -> int
2186
2187       Same as Unix.getsockopt for an integer-valued socket option.
2188
2189
2190
2191       val setsockopt_int : file_descr -> socket_int_option -> int -> unit
2192
2193       Same as Unix.setsockopt for an integer-valued socket option.
2194
2195
2196
2197       val  getsockopt_optint  : file_descr -> socket_optint_option -> int op‐
2198       tion
2199
2200       Same as Unix.getsockopt for a socket option whose value is an  int  op‐
2201       tion .
2202
2203
2204
2205       val  setsockopt_optint  : file_descr -> socket_optint_option -> int op‐
2206       tion -> unit
2207
2208       Same as Unix.setsockopt for a socket option whose value is an  int  op‐
2209       tion .
2210
2211
2212
2213       val getsockopt_float : file_descr -> socket_float_option -> float
2214
2215       Same  as  Unix.getsockopt  for  a socket option whose value is a float‐
2216       ing-point number.
2217
2218
2219
2220       val setsockopt_float : file_descr -> socket_float_option  ->  float  ->
2221       unit
2222
2223       Same  as  Unix.setsockopt  for  a socket option whose value is a float‐
2224       ing-point number.
2225
2226
2227
2228       val getsockopt_error : file_descr -> error option
2229
2230       Return the error condition associated with the given socket, and  clear
2231       it.
2232
2233
2234
2235
2236   High-level network connection functions
2237       val open_connection : sockaddr -> in_channel * out_channel
2238
2239       Connect  to  a  server at the given address.  Return a pair of buffered
2240       channels connected to the server.  Remember to call flush on the output
2241       channel at the right times to ensure correct synchronization.
2242
2243       The  two  channels  returned by open_connection share a descriptor to a
2244       socket.  Therefore, when  the  connection  is  over,  you  should  call
2245       close_out  on  the output channel, which will also close the underlying
2246       socket.  Do not call close_in on the input channel;  it  will  be  col‐
2247       lected by the GC eventually.
2248
2249
2250
2251       val shutdown_connection : in_channel -> unit
2252
2253       ``Shut down'' a connection established with Unix.open_connection ; that
2254       is, transmit an end-of-file condition to  the  server  reading  on  the
2255       other  side  of  the connection. This does not close the socket and the
2256       channels used by the connection.  See Unix.open_connection for  how  to
2257       close them once the connection is over.
2258
2259
2260
2261       val  establish_server : (in_channel -> out_channel -> unit) -> sockaddr
2262       -> unit
2263
2264       Establish a server on the given address.  The function given  as  first
2265       argument  is called for each connection with two buffered channels con‐
2266       nected to the client. A new process is created for each connection. The
2267       function Unix.establish_server never returns normally.
2268
2269       The  two channels given to the function share a descriptor to a socket.
2270       The function does not need to close the channels, since this occurs au‐
2271       tomatically  when  the  function  returns.  If the function prefers ex‐
2272       plicit closing, it should close the output channel using close_out  and
2273       leave   the   input   channel   unclosed,   for  reasons  explained  in
2274       Unix.in_channel_of_descr .
2275
2276       On Windows: not implemented (use threads).
2277
2278
2279
2280
2281   Host and protocol databases
2282       type host_entry = {
2283        h_name : string ;
2284        h_aliases : string array ;
2285        h_addrtype : socket_domain ;
2286        h_addr_list : inet_addr array ;
2287        }
2288
2289
2290       Structure of entries in the hosts database.
2291
2292
2293       type protocol_entry = {
2294        p_name : string ;
2295        p_aliases : string array ;
2296        p_proto : int ;
2297        }
2298
2299
2300       Structure of entries in the protocols database.
2301
2302
2303       type service_entry = {
2304        s_name : string ;
2305        s_aliases : string array ;
2306        s_port : int ;
2307        s_proto : string ;
2308        }
2309
2310
2311       Structure of entries in the services database.
2312
2313
2314
2315       val gethostname : unit -> string
2316
2317       Return the name of the local host.
2318
2319
2320
2321       val gethostbyname : string -> host_entry
2322
2323       Find an entry in hosts with the given name.
2324
2325
2326       Raises Not_found if no such entry exists.
2327
2328
2329
2330       val gethostbyaddr : inet_addr -> host_entry
2331
2332       Find an entry in hosts with the given address.
2333
2334
2335       Raises Not_found if no such entry exists.
2336
2337
2338
2339       val getprotobyname : string -> protocol_entry
2340
2341       Find an entry in protocols with the given name.
2342
2343
2344       Raises Not_found if no such entry exists.
2345
2346
2347
2348       val getprotobynumber : int -> protocol_entry
2349
2350       Find an entry in protocols with the given protocol number.
2351
2352
2353       Raises Not_found if no such entry exists.
2354
2355
2356
2357       val getservbyname : string -> string -> service_entry
2358
2359       Find an entry in services with the given name.
2360
2361
2362       Raises Not_found if no such entry exists.
2363
2364
2365
2366       val getservbyport : int -> string -> service_entry
2367
2368       Find an entry in services with the given service number.
2369
2370
2371       Raises Not_found if no such entry exists.
2372
2373
2374       type addr_info = {
2375        ai_family : socket_domain ;  (* Socket domain
2376        *)
2377        ai_socktype : socket_type ;  (* Socket type
2378        *)
2379        ai_protocol : int ;  (* Socket protocol number
2380        *)
2381        ai_addr : sockaddr ;  (* Address
2382        *)
2383        ai_canonname : string ;  (* Canonical host name
2384        *)
2385        }
2386
2387
2388       Address information returned by Unix.getaddrinfo .
2389
2390
2391       type getaddrinfo_option =
2392        | AI_FAMILY of socket_domain
2393         (* Impose the given socket domain
2394        *)
2395        | AI_SOCKTYPE of socket_type
2396         (* Impose the given socket type
2397        *)
2398        | AI_PROTOCOL of int
2399         (* Impose the given protocol
2400        *)
2401        | AI_NUMERICHOST  (* Do not call name resolver, expect numeric IP  ad‐
2402       dress
2403        *)
2404        | AI_CANONNAME  (* Fill the ai_canonname field of the result
2405        *)
2406        | AI_PASSIVE  (* Set address to ``any'' address for use with Unix.bind
2407
2408        *)
2409
2410
2411       Options to Unix.getaddrinfo .
2412
2413
2414
2415       val  getaddrinfo  :  string  ->  string  ->  getaddrinfo_option list ->
2416       addr_info list
2417
2418
2419       getaddrinfo host service opts returns a list of Unix.addr_info  records
2420       describing  socket  parameters and addresses suitable for communicating
2421       with the given host and service.  The empty list  is  returned  if  the
2422       host or service names are unknown, or the constraints expressed in opts
2423       cannot be satisfied.
2424
2425
2426       host is either a host name or the string representation of  an  IP  ad‐
2427       dress.   host  can  be  given  as  the  empty string; in this case, the
2428       ``any'' address or the ``loopback'' address are used, depending whether
2429       opts  contains  AI_PASSIVE  .   service is either a service name or the
2430       string representation of a port number.  service can be  given  as  the
2431       empty string; in this case, the port field of the returned addresses is
2432       set to 0.  opts is a possibly empty list of  options  that  allows  the
2433       caller  to  force  a  particular  socket domain (e.g. IPv6 only or IPv4
2434       only) or a particular socket type (e.g. TCP only or UDP only).
2435
2436
2437       type name_info = {
2438        ni_hostname : string ;  (* Name or IP address of host
2439        *)
2440        ni_service : string ;  (* Name of service or port number
2441        *)
2442        }
2443
2444
2445       Host and service information returned by Unix.getnameinfo .
2446
2447
2448       type getnameinfo_option =
2449        | NI_NOFQDN  (* Do not qualify local host names
2450        *)
2451        | NI_NUMERICHOST  (* Always return host as IP address
2452        *)
2453        | NI_NAMEREQD  (* Fail if host name cannot be determined
2454        *)
2455        | NI_NUMERICSERV  (* Always return service as port number
2456        *)
2457        | NI_DGRAM  (* Consider the service as UDP-based instead  of  the  de‐
2458       fault TCP
2459        *)
2460
2461
2462       Options to Unix.getnameinfo .
2463
2464
2465
2466       val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2467
2468
2469       getnameinfo  addr  opts  returns  the host name and service name corre‐
2470       sponding to the socket address addr .  opts is a possibly empty list of
2471       options that governs how these names are obtained.
2472
2473
2474       Raises Not_found if an error occurs.
2475
2476
2477
2478
2479   Terminal interface
2480       The  following  functions  implement the POSIX standard terminal inter‐
2481       face. They provide control over asynchronous  communication  ports  and
2482       pseudo-terminals. Refer to the termios man page for a complete descrip‐
2483       tion.
2484
2485       type terminal_io = {
2486
2487       mutable c_ignbrk : bool ;  (* Ignore the break condition.
2488        *)
2489
2490       mutable c_brkint : bool ;  (* Signal interrupt on break condition.
2491        *)
2492
2493       mutable c_ignpar : bool ;  (* Ignore characters with parity errors.
2494        *)
2495
2496       mutable c_parmrk : bool ;  (* Mark parity errors.
2497        *)
2498
2499       mutable c_inpck : bool ;  (* Enable parity check on input.
2500        *)
2501
2502       mutable c_istrip : bool ;  (* Strip 8th bit on input characters.
2503        *)
2504
2505       mutable c_inlcr : bool ;  (* Map NL to CR on input.
2506        *)
2507
2508       mutable c_igncr : bool ;  (* Ignore CR on input.
2509        *)
2510
2511       mutable c_icrnl : bool ;  (* Map CR to NL on input.
2512        *)
2513
2514       mutable c_ixon : bool ;  (* Recognize XON/XOFF characters on input.
2515        *)
2516
2517       mutable c_ixoff : bool ;  (* Emit XON/XOFF chars to control input flow.
2518        *)
2519
2520       mutable c_opost : bool ;  (* Enable output processing.
2521        *)
2522
2523       mutable c_obaud : int ;  (* Output baud rate  (0  means  close  connec‐
2524       tion).
2525        *)
2526
2527       mutable c_ibaud : int ;  (* Input baud rate.
2528        *)
2529
2530       mutable c_csize : int ;  (* Number of bits per character (5-8).
2531        *)
2532
2533       mutable c_cstopb : int ;  (* Number of stop bits (1-2).
2534        *)
2535
2536       mutable c_cread : bool ;  (* Reception is enabled.
2537        *)
2538
2539       mutable c_parenb : bool ;  (* Enable parity generation and detection.
2540        *)
2541
2542       mutable c_parodd : bool ;  (* Specify odd parity instead of even.
2543        *)
2544
2545       mutable c_hupcl : bool ;  (* Hang up on last close.
2546        *)
2547
2548       mutable c_clocal : bool ;  (* Ignore modem status lines.
2549        *)
2550
2551       mutable c_isig : bool ;  (* Generate signal on INTR, QUIT, SUSP.
2552        *)
2553
2554       mutable c_icanon : bool ;  (* Enable canonical processing (line buffer‐
2555       ing and editing)
2556        *)
2557
2558       mutable c_noflsh : bool ;  (* Disable flush after INTR, QUIT, SUSP.
2559        *)
2560
2561       mutable c_echo : bool ;  (* Echo input characters.
2562        *)
2563
2564       mutable c_echoe : bool ;  (* Echo ERASE (to erase previous character).
2565        *)
2566
2567       mutable c_echok : bool ;  (* Echo KILL (to erase the current line).
2568        *)
2569
2570       mutable c_echonl : bool ;  (* Echo NL even if c_echo is not set.
2571        *)
2572
2573       mutable c_vintr : char ;  (* Interrupt character (usually ctrl-C).
2574        *)
2575
2576       mutable c_vquit : char ;  (* Quit character (usually ctrl-\).
2577        *)
2578
2579       mutable c_verase : char ;  (* Erase character (usually DEL or ctrl-H).
2580        *)
2581
2582       mutable c_vkill : char ;  (* Kill line character (usually ctrl-U).
2583        *)
2584
2585       mutable c_veof : char ;  (* End-of-file character (usually ctrl-D).
2586        *)
2587
2588       mutable c_veol : char ;  (* Alternate end-of-line char. (usually none).
2589        *)
2590
2591       mutable c_vmin : int ;  (* Minimum number of characters to read  before
2592       the read request is satisfied.
2593        *)
2594
2595       mutable c_vtime : int ;  (* Maximum read wait (in 0.1s units).
2596        *)
2597
2598       mutable c_vstart : char ;  (* Start character (usually ctrl-Q).
2599        *)
2600
2601       mutable c_vstop : char ;  (* Stop character (usually ctrl-S).
2602        *)
2603        }
2604
2605
2606
2607
2608
2609       val tcgetattr : file_descr -> terminal_io
2610
2611       Return  the  status  of  the terminal referred to by the given file de‐
2612       scriptor.
2613
2614       On Windows: not implemented.
2615
2616
2617       type setattr_when =
2618        | TCSANOW
2619        | TCSADRAIN
2620        | TCSAFLUSH
2621
2622
2623
2624
2625
2626       val tcsetattr : file_descr -> setattr_when -> terminal_io -> unit
2627
2628       Set the status of the terminal referred to by the given  file  descrip‐
2629       tor.  The second argument indicates when the status change takes place:
2630       immediately ( TCSANOW ), when all pending output has been transmitted (
2631       TCSADRAIN ), or after flushing all input that has been received but not
2632       read ( TCSAFLUSH ).  TCSADRAIN is recommended when changing the  output
2633       parameters; TCSAFLUSH , when changing the input parameters.
2634
2635       On Windows: not implemented.
2636
2637
2638
2639       val tcsendbreak : file_descr -> int -> unit
2640
2641       Send  a break condition on the given file descriptor.  The second argu‐
2642       ment is the duration of the break, in 0.1s units; 0 means standard  du‐
2643       ration (0.25s).
2644
2645       On Windows: not implemented.
2646
2647
2648
2649       val tcdrain : file_descr -> unit
2650
2651       Waits  until  all  output written on the given file descriptor has been
2652       transmitted.
2653
2654       On Windows: not implemented.
2655
2656
2657       type flush_queue =
2658        | TCIFLUSH
2659        | TCOFLUSH
2660        | TCIOFLUSH
2661
2662
2663
2664
2665
2666       val tcflush : file_descr -> flush_queue -> unit
2667
2668       Discard data written on the given file descriptor but not yet transmit‐
2669       ted,  or  data received but not yet read, depending on the second argu‐
2670       ment: TCIFLUSH flushes data received but  not  read,  TCOFLUSH  flushes
2671       data written but not transmitted, and TCIOFLUSH flushes both.
2672
2673       On Windows: not implemented.
2674
2675
2676       type flow_action =
2677        | TCOOFF
2678        | TCOON
2679        | TCIOFF
2680        | TCION
2681
2682
2683
2684
2685
2686       val tcflow : file_descr -> flow_action -> unit
2687
2688       Suspend  or restart reception or transmission of data on the given file
2689       descriptor, depending on the second argument: TCOOFF  suspends  output,
2690       TCOON restarts output, TCIOFF transmits a STOP character to suspend in‐
2691       put, and TCION transmits a START character to restart input.
2692
2693       On Windows: not implemented.
2694
2695
2696
2697       val setsid : unit -> int
2698
2699       Put the calling process in a new session and detach it  from  its  con‐
2700       trolling terminal.
2701
2702       On Windows: not implemented.
2703
2704
2705
2706
2707
2708OCamldoc                          2022-02-04                           Unix(3)
Impressum