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

NAME

6       UnixLabels - Interface to the Unix system.
7

Module

9       Module   UnixLabels
10

Documentation

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