libs/src/misc/misc.3

   1 .\"(c) Copyright 1992 by Panagiotis Tsirigotis
   2 .\"All rights reserved.  The file named COPYRIGHT specifies the terms
   3 .\"and conditions for redistribution.
   4 .\"
   5 .\" $Id: misc.3,v 1.1.1.1 2003/02/19 17:29:27 bbraun Exp $
   6 .TH MISC 3X "25 January 1992"
   7 .SH NAME
   8 make_string, make_pathname, argv_copy_and_clear, basename, dirname - miscellaneous functions
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 .ft B
  13 #include "misc.h"
  14 .LP
  15 .ft B
  16 char *make_string( count, ... )
  17 unsigned count ;
  18 .LP
  19 .ft B
  20 char *make_pathname( count, ... )
  21 unsigned count ;
  22 .LP
  23 .ft B
  24 char **argv_copy_and_clear( argv, start, count )
  25 char **argv ;
  26 int start, count ;
  27 .LP
  28 .ft B
  29 char *dirname( path )
  30 char *path ;
  31 .LP
  32 .ft B
  33 char *basename( path )
  34 char *path ;
  35 .SH DESCRIPTION
  36 .LP
  37 This library contain miscellaneous functions, hence the name.
  38 .LP
  39 .B make_string()
  40 creates a string by catenating the list of strings passed as arguments.
  41 \fIcount\fR indicates how many strings there are.
  42 Strings that are
  43 .SM NULL
  44 pointers are ignored.
  45 \fBmake_string()\fR returns malloc'ed memory.
  46 .LP
  47 .B make_pathname()
  48 creates a pathname by catenating the list of pathname components passed
  49 as arguments and inserting slashes between them.
  50 \fIcount\fR indicates how many components there are.
  51 \fBmake_pathname()\fR returns malloc'ed memory.
  52 .LP
  53 .B argv_copy_and_clear()
  54 creates a new argv array of size \fIcount\fR, and fills it with the
  55 contents of \fIargv\fR from \fIstart\fR up to \fIstart+count-1\fR.
  56 The original \fIargv\fR entries in that range are cleared by filling
  57 them with
  58 .SM SPACEs.
  59 .LP
  60 .B dirname()
  61 returns in a malloced string containing all but the last of
  62 component of \fIpath\fR. There are 2 special cases:
  63 first when the
  64 \fIpath\fR is "/", \fBdirname()\fR will return "/",
  65 and second, when the \fIpath\fR does not contain any '/',
  66 \fBdirname()\fR will return ".".
  67 .LP
  68 .B basename()
  69 returns a pointer to the last component of \fIpath\fR.
  70 .SH "RETURN VALUES"
  71 .LP
  72 \fBmake_string()\fR returns a pointer to the new string.
  73 It returns
  74 .SM NULL
  75 if \fIcount\fR is 0.
  76 .LP
  77 \fBmake_pathname()\fR returns a pointer to the new pathname.
  78 It returns
  79 .SM NULL
  80 if \fIcount\fR is 0.
  81 .LP
  82 \fBargv_copy_and_clear()\fR returns the new argv array. It returns
  83 .SM NULL
  84 if \fImalloc\fR fails to allocate more memory.
  85 .LP
  86 \fBdirname()\fR returns a new string or
  87 .SM NULL
  88 if \fImalloc\fR fails to allocate more memory.
  89 .LP
  90 \fBbasename()\fR returns a pointer to the last component of \fIpath\fR.
  91 .SH BUGS
  92 .LP
  93 The behavior of \fBdirname()\fR and \fBbasename()\fR is undefined if
  94 they are given a zero-length string.